Lab 4: Atmel XPlained Pro Demo

This lab will demonstrate how to connect a Modulo-2 development board to an Atmel SAMD21 Xplained Pro development board using the Atmel “Afero-Mod2 Xplained Pro” interface board. You will use Atmel Studio 7 to compile a sample application and download it to the SAMD21 Xplained Pro board.

This lab will take about an hour, depending on your familiarity with the SAMD21 Xplained Pro board and the Atmel Studio development environment.

Prerequisites

You should have completed the Afero Profile Editor Lab, and be able to modify a profile and publish it to a Modulo-2 development board over-the-air.

Tools/Materials

For this lab, you will need the following pieces of hardware, all supplied in your lab hardware kit:

  • Atmel SAMD21 Xplained Pro Evaluation Kit
  • Atmel “Afero-Mod2” Xplained Pro Interface Board to connect your Modulo-2 to the SAMD21 board
  • A computer running Microsoft Windows (go to www.atmel.com/tools/atmelstudio.aspx for minimum Atmel Studio OS requirements)
  • iOS or Android mobile phone, running:
    • Android KitKat 4.4 (API Level 19), or
    • iOS release 9.3
  • Afero Modulo-2 development board
  • Micro-USB cable to power the Modulo-2 (there is one in the Afero-Mod2 board kit)
  • USB power source (free USB port on a computer, AC wall adapter, or portable charger)

Atmel Studio Setup

If you’ve previously used Atmel Studio on your computer, you can skip to Lab Project Setup to install the lab files.


  1. Download Atmel Studio 7 from http://www.microchip.com/development-tools/atmel-studio-7.
  2. Double-click the Atmel Studio Installer and follow the default prompts to install AS7. You will need to check the I agree to the license terms and conditions box on the first page to continue the install. Beyond that leave all the installation prompts at their defaults.
  3. Windows 7 users: the installation may pause and request two specific Windows Updates to be installed. You will see the Windows Update installation step fail. If this happens:
    1. The installer will require you to install two updates before Atmel Studio can be installed:
    2. Copy the two URLs listed in the error message, then paste them into a browser to install the required updates. Select the updates for your specific version and architecture of Windows. Use the system Control Panel to verify your version of Windows and if it’s 32-bit or 64-bit: Computer Info
    3. Install the two required updates. A reboot is not needed after installation.
    4. Click Refresh in the Atmel Studio installer to re-run the installation checks, and this time they will pass, so click Next to continue the installation.

      If you can’t install these updates for any reason, you can click Next in the Atmel Studio installer to continue without them. For the purposes of this lab, those updates aren’t important.


  4. If you receive a note about “Header File Versions” being updated, go ahead and click Install on that screen to continue.
  5. Continue following the prompts to install Atmel Studio 7 until the installation completes. On the last screen, ensure the Launch Atmel Studio 7 checkbox is checked and then click Close to close the installer and launch AS7. Atmel Studio Install Complete
  6. When AS7 launches, click the Minimize icon in the upper-right corner. Now we can download and install the lab project file and set it up.

Lab Project Setup

  1. Download the lab project file, afLibD21.zip. Save this file to the Downloads folder on your computer.
  2. Open File Explorer on your computer from the Start menu or from the taskbar. Click the Downloads folder in the left pane, then double-click the afLibD21 compressed folder shown.
  3. Inside that file, right-click the afLibD21 folder and select Copy: Copy File
  4. In the left pane, expand the folder list until you can see the Atmel Studio 7 projects folder.

    Windows 7 Users: Expand Libraries > Documents > My Documents > Atmel Studio > 7.0. Right-click the 7.0 folder and select Paste:

    Paste

    Windows 10 Users: Expand This PC > Documents > Atmel Studio > 7.0. Right-click the 7.0 folder and select Paste: Paste

  5. Double-click the 7.0 folder, then double-click the afLibD21 folder to open the project’s files. Double-click the afLibD21 ATMEL Studio 7.0 solution file (with the red icon) to open the project in Atmel Studio: Open Project
  6. If you have just installed Atmel Studio, you will be prompted to install an Update Pack for the SAMD21 board; ensure the Update to version matches the Missing version.
    1. Click Download and Install. Installation only takes a few moments.
    2. When it completes, click Close on the Pack Manager screen, then Close again on the Update Pack screen.
    3. Close Atmel Studio 7 and relaunch the application by double-clicking the afLibD21 solution file, which should still be open in the File Manager on your computer. If not, open your Documents folder, expand Atmel Studio, expand 7.0, expand the afLibD21 folder, then double-click the afLibD21 solution file to relaunch Atmel Studio. Relaunch Atmel Studio

Build the Lab Project

  1. After Atmel Studio relaunches, find the Solution Explorer window in the right side of the AS7 workspace. If you can’t see the Solution Explorer window, close the VA View window or any other window open above it.

    The Solution Explorer will list out the files in the project and let you review or modify them. Scroll to the file main.cpp; click to open it in the workspace so we can review how it works.

  2. In the Build menu at the top of the screen, select Build Solution to build the project. It will take a minute or so. Ignore any warnings or messages, the solution should build with 0 errors: 0 Error Build

Configure Your Modulo-2 Board

We need to install a profile to your Modulo-2 board that supports the attributes used by this project. By now, you should be pretty familiar with the Afero Profile Editor, so we’ll take a shortcut here and use a preinstalled profile.

  1. Minimize Atmel Studio by clicking the Minimize icon in the upper-right of the window.
  2. Launch Afero Profile Editor, sign in if requested, and select Open to open a local device profile.
  3. In the File Explorer window, select your Documents folder, and drill down to Documents > Atmel Studio > 7.0 > afLibD21 > afLibD21 (again) > profile. In that folder you will see two other folders, afBlink and afBlink2.

    For the Modulo-2 board, click the afBlink2 folder once, and then click Select Folder. The profile will open.

  4. Detach your Modulo-2 board from any previous hardware it’s connected to and plug it in to a USB port with a Micro-USB cable, all by itself.
  5. Select Publish in the left-hand nav bar. When the Modulo-2 comes online, publish the profile to your board. At this point you should be pretty familiar with the process; if not, please review the materials in Lab 2. Device Profile

    Once your Modulo-2 has the afBlink2 profile loaded onto it, proceed to the next section.

Assemble the Lab Hardware and Download the Application

  1. Remove the SAMD21 XPlained Pro and the Afero-Mod2 Xplained Pro interface board from their packaging.

    Unplug your Modulo-2 board and insert it into the interface board. The USB port of the Modulo-2 should be in the same direction as the connector of the interface board. The connection should be fairly tight, and you will have to press the board down until the connector “clicks” to seat it properly. Take care to not bend any pins on the Modulo-2 board as you insert it.

    Modulo Board
  2. Connect this interface board to the EXT1 connector of the SAMD21 board as shown: Connect to SAMD21 board
  3. Connect the SAMD21 board to your computer with a Micro-USB cable. Plug the cable into the DEBUG USB port on the SAMD21. Do not connect a cable to the TARGET USB port.
  4. Windows may install device drivers for the board, which will take a few moments. If Windows Autoplay pops up to ask you what you want to do with the device, just click the Close button on that window.

    The SAMD21 board should pop up in Atmel Studio once it’s connected. The extension board may be listed as “Unknown” because it’s a new board design. This is OK.

    SAMD21 Board in Atmel Studio
  5. Download the application to the SAMD21 board. Click the Debug menu at the top of the window and select Start without Debugging. This will download the application to the SAMD21 board and start executing it.

    If you get any errors connecting to the SAMD21 board, please check that the hardware debugger and board type are correct:

    • Click the Tools/Device Programming menu, and ensure that the EDBG tool and the SAMD21 device are selected. If they are not, select them and click Apply.
      Device Programming Window
    • Disconnect and reconnect the SAMD21 board. You should be able to continue.

Blink an LED

  1. In the Afero mobile app, select your Modulo-2 device. The profile will have a Blink menu with Off and On buttons. Tap On and note that the LED on the Modulo-2 will start blinking. Tap Off and the LED will stop blinking.
  2. Back in Atmel Studio, locate the main.cpp code window. If it’s closed, go back to the Solution Explorer window and click main.cpp to open it. You can close some of the other windows in this workspace to get a larger view of the code.

What’s Happening?

When you tap the Blink button in the mobile app UI, that attribute (BLINK) is sent to the MCU. The MCU receives this update via the attrSetHandler function in the code:

bool attrSetHandler(const uint8_t requestId, const uint16_t attributeId, const uint16_t valueLen, const uint8_t *value) {
    printAttribute("attrSetHandler", attributeId, valueLen, value);

    switch (attributeId) {
        // This MCU attribute tells us whether we should be blinking.
        case AF_BLINK:
            blinking = (*value == 1);
            break;

When the BLINK attribute changes, the value passed to this code is 0 or 1 (for “Off” or “On”). This code will turn on the local Boolean variable “blinking” to tell the MCU whether it should be blinking the Modulo-2 LED or not.

If you look in the loop function, you can see this in action:

void loop() {
	if (blinking) {
		if (millis() - lastBlink > BLINK_INTERVAL) {
			toggleModuloLED();
			lastBlink = millis();
		}
		} else {
		setModuloLED(false);
	}

	// Give the afLib state machine some time.
	aflib->loop();
}

One thing to note there is the call to aflib->loop() at the bottom of this function. afLib itself needs a little CPU time to process its queue of outgoing attribute updates (if there are any) and to check for incoming attribute changes coming from the Afero Cloud (if there are any of those). It’s important to give afLib enough CPU time to process these tasks, so in any idle loop of your MCU code, please ensure that afLib’s loop() function gets called as often as possible. If afLib has to work to do, this loop will return immediately.

The toggleModuloLED function changes the LED on the Modulo-2 by setting the Afero attribute for the LED to on or off:

void toggleModuloLED() {
    setModuloLED(!moduloLEDIsOn);
}

void setModuloLED(bool on) {
    if (moduloLEDIsOn != on) {
        int16_t attrVal = on ? LED_ON : LED_OFF; // Modulo LED is active low
        while (aflib->setAttribute16(AF_MODULO_LED, attrVal) != afSUCCESS) {
            printf("Could not set LED\r\n");
	        aflib->loop();
        }
        moduloLEDIsOn = on;
    }
}

When the MCU sets the LED attribute via the setAttribute16 function, this attribute change is sent to the Modulo-2 board via afLib, which in turn sets the LED and sends the attribute update to the Afero Cloud. As the LED on the board changes, you can see the LED attribute in the mobile app reflect the LED state as it changes.

Be sure to check out the attrNotifyHandler function as well; this function is called when the MCU changes an attribute or when the Modulo-2 sends a default attribute value to the MCU. In general, you will get an attrNotifyHandler event any time an attribute value changes that the MCU doesn’t know about. If an attribute is specifically set by the Afero Cloud, you will also get an attrSetHandler event so that remote attribute changes can be handled differently if needed. There is a lot of overlap in functionality between these two handlers and for some simple MCU applications it may only be necessary to use one or the other.