AVR1913: Display Xplained Firmware - Getting Started

Features
QVGA (320x240) LCD with resistive touch panel Display Xplained software library - Graphical library: low level graphics, windows and widgets - Desktop application with clickable icons - Picture viewer application Tiny Simple File System (TSFS) image generation Write file system image directly to USB mass-storage block devices

8-bit Microcontrollers Application Note

1 Introduction
The Display Xplained board is a display extension board to the Xplain series of boards. Featured on the board is a QVGA (320x240) LCD with a resistive touch film on top. Since the board does not come with its own microcontroller, it is designed to be controlled by another of the Xplain series of boards with an AVR microcontroller. It is assumed you have an Xplain series board attached to the Display Xplained board in this application note. Out of the box the Display Xplained firmware will be a desktop with icons for the different applications that the user can start. One of the applications is a simple picture frame, which scans any appropriate flash memory on the Xplain board and displays supported pictures on the LCD screen. Users can interact by using the resistive touch to navigate in the pictures and start/stop the automatic slideshow. This application note will step you through how to compile and upload the software framework application targeted for Display Xplained. It will also guide you through generating a Tiny Simple file system image and upload this to the Xplain flash memory. In this application note there is also an appendix which steps through a much simpler application as an example of how to use the Display Xplained software framework. Figure 1-1. Display Xplained desktop application

Rev. 8294A-AVR-04/10

2 Development Prerequisites
The software framework requires that some essential software is preinstalled before a developer starts using the Display Xplained software framework build system. This section will cover the basics needed.

2.1 Toolchain for AVR Microcontrollers

Source code used in this project is made to be used with both GNU GCC and IARTM toolchains. A list of supported toolchains is: IAR Embedded Workbench for AVR, available through www.iar.se. WinAVR provides avr-gcc, available through winavr.sf.net.

2.2 Required Software Tools

The software framework build system assumes that you have some basic software tools installed on the build machine. These tools are easy to install on most modern operating systems. On Microsoft Windows systems these software applications are installed with the WinAVR package, while on Linux systems they are usually available using the distributions package system. Software which must be installed for the software framework to be useful: make, sed, grep, sort, tac, bc, etc., often referred to as build essentials. sh command interpreter (shell) The software framework also requires Microsoft Windows users to have a C:\tmp directory, or if your Microsoft Windows installation is located on another drive, this drive needs to have a top level tmp directory. 2.2.1 Python Software Command line tools for preparing graphics files and for generating and writing new file system images to the flash memory on the Xplain board are supplied with this application note, along with their source code. These tools have been written in the Python programming language. For Windows systems, precompiled executables have been made available. A Python interpreter is therefore only required if the developer wishes to modify the tools, or if the executables for some reason do not function on his system. On Linux systems, Python must be installed if the developer wants to use the tools. See chapters 5.2.2 How to Prepare Graphics for Display Xplained, 5.2.3 How to Generate a Tiny Simple File System Image File and 5.2.4 How to Upload a File System Image to Board Flash Memory for more information on these tools. Python can be downloaded and installed from http://www.python.org/download

AVR1913
8294A-AVR-04/10

AVR1913
2.2.1.1 Python Extras for Windows Users Microsoft Windows Users that wants to run the Python scripts directly (not using the pre-built binaries) will need three additional Python packages: The tool described in chapter 5.2.2 How to Prepare Graphics for Display Xplained requires the extension PIL, short for Python Imaging Library. PIL can be downloaded and installed from http://www.pythonware.com/products/pil/ The tool described in chapter 5.2.4 How to Upload a File System Image to Board Flash Memory relies on two extensions called pywin32 and WMI, short for Windows Management Instrumentation. Pywin32 can be downloaded and installed from http://sourceforge.net/projects/pywin32 WMI can be downloaded and installed from http://timgolden.me.uk/python/wmi 2.2.2 Programming Tools Developers will need certain programming tools to be able to upload firmware to the target device. For 8-bit AVR devices users can select between: Avrdude part of WinAVR and available in most Linux distributions. Atmel AVR Studio on Microsoft Windows machines. Also a hardware programmer capable of interfacing AVR devices is needed. The programmer must of course be supported by the tools listed above. Programmers provided by Atmel: AVR Dragon AVRISP (replaced by AVRISP mkII) AVRISP mkII AVR ONE! JTAGICE (replaced by JTAGICE mkII) JTAGICE mkII

2.3 Development Environment

Modern x86 computers are highly usable for developing and deploying firmware for 8bit AVR microcontrollers. Users must make sure their computer matches the minimal requirements for the toolchain, and the graphical frontend if in use.

2.4 Display Xplained Software Framework

The software framework for Display Xplained is supplied in the compressed file archive available along side this application note.

2.5 Xplain Board Controller

For Xplain boards with multiple devices it is required to enable the mass-storage feature for the board controller. This is required when the user wants to add image data to the onboard flash memory. There is a separate application note covering the board controller on Xplain boards. 3
8294A-AVR-04/10

3 Display Xplained Software Framework Directory Structure

The software framework is split into different directories from the top level. This is done to order the different systems from each other and make it easier to work with different sub systems once you know what is where. 3.1.1 Apps Directory All the applications which use different parts of the software framework are stored in the apps/ directory. Each application resides in its own sub directory. More details about how each application is configured and implemented can be found the appendix, chapter 7 Appendix A: Introduction to the UART Loopback Application on page 23. 3.1.2 Arch Directory Cross architecture support is implemented by separating out the common architecture features into the arch/ directory. This directory will contain sub directories for each of the supported architectures. For the Display Xplained software framework the 8-bit AVR architecture is present. The architecture part takes care of common parts for all chips in that architecture. This includes implementation of assembly startup code before calling the main function, compiler abstractions and basic architecture functions like sleep, string functions, interrupt handling and software interrupts. 3.1.3 Board Directory In the board/ directory there is one sub directory for each board the many applications can be configured to run on. Each board directory contains what the application code would need to know about each board, since one application can run on several boards. Each board usually contains setup of different hardware attached to the board, like LEDs, buttons, chip selects to SPI devices, external memory, etc. 3.1.4 Build Directory When a user does a make in an application the output files is stored in the build/ directory. This directory will contain a number of sub directories depending on how many applications and boards the user compiles code for. All the object files, list files, elf files, hex files and documentation will end up here. A typical example of content when compiling the display-demo application with GNU GCC is that the output files will end up in build/display-demo/xplain/GNU. 3.1.5 Chip Directory The chip/ directory contain one sub directory for each unique AVR device supported by the software framework; these directories will contain specific device behavior for each chip supported. 3.1.6 CPU Directory Between chip and architecture level there is a cpu/ directory, here the code and defines common for a CPU family are structured. There will be one sub directory for each family, like xmega/ for the Atmel AVR XMEGATM family. 4

AVR1913
8294A-AVR-04/10

AVR1913
3.1.7 Doc Directory In the doc/ directory users will find source code files with additional documentation for the interfaces available through drivers, various software stacks, protocols and software utilities. The content of each file is usually pure Doxygen style documentation, and added by default when users build documentation for their application. Reading documentation directly from the doc/ directory is not recommended, as it is in Doxygen format. For building the Doxygen documentation for an application see section 4.1 Available Make Targets the Help Menu on page 6. 3.1.8 Drivers Directory All hardware drivers are located in the drivers/ directory. Hardware drivers include both on-chip hardware and external hardware like flash memory. Hardware drivers will have a common interface for all architectures, but may have different implementations all the way down to chip level. 3.1.9 Include Directory The include/ directory contains all the header files defining the various application programming interfaces (API) in the software framework. This is where users should include interfaces to drivers, software stacks and code utilities when making an application. 3.1.10 Make Directory Display Xplained software framework has its own build system which is located in the make/ directory. Regular users should not need to alter any of the different files located here. Shortly summarized there is one file, subdir.mk, in all directories from the top level containing code. This file tells the build system what to build depending on the configuration the user has chosen. 3.1.11 Util Directory All the common utilities like string utilities, queue management, lists, etc. is in the util/ directory. The utilities are not dependent on any drivers or hardware, but they are often used by the various drivers.

5
8294A-AVR-04/10

4 Display Xplained Software Framework Build System

The software framework includes its own build system consisting of a large number of Makefiles. Configuring and using the build system is done in the applications directory through a Makefile and a configuration file with defined symbols.

4.1 Available Make Targets the Help Menu

The build system has an integrated help menu; this lists the different make targets and gives a short introduction to their usage. The help menu will also list the most frequently used variables used to alter the behavior of make when building an application. Example: Display Xplained software framework build system help target
~ > make help Usage: make [CONFIG_VARIABLE=VALUE]... [TARGET]... Available targets: all Default target if no target is specified. This will build the default configuration for this application. docs Generate documentation for the selected configuration. tar-archive Pack all application files into an archive. archive-check Pack all application files into an archive, unpack them again and build the application from the archive files. clean Delete ELF file and all intermediate build products. program Build the ELF file and program it onto the flash on the target. run Start executing code on the target. reset Reset the target. help This help text. Build system configuration variables: CONFIG Configuration to build. If none is given the default configuration is used. Each configuration needs a corresponding config file in the application directory. E.g. to build the config-atevk1104.mk configuration, run 'make CONFIG=atevk1104'. V Set to 1 for verbose output. TOOLCHAIN Toolchain to use for the build, GNU or IAR. The default toolchain is specified in the application Makefile. IAR_PATH Path to IAR EWB installation. Further information is available in doc/build_system_doc.c

AVR1913
8294A-AVR-04/10

AVR1913
4.2 Building an Application
To build an application, simply enter the appropriate directory under the apps/ directory and type make. A new directory, if it did not exist already, is created under the top level build/ directory. In this directory the results of the build process will be stored. After performing this step once, subsequent builds can be done either by running make from the application directory as before, or by running make from the build directory. Each application has a default configuration file for which the application will be built unless otherwise specified, as well as a default toolchain to use. To build the application with a different configuration, simply set the CONFIG environment variable to the name of the desired configuration when running make, for example like this:
make CONFIG=xplain

To use a different toolchain than the default, set the TOOLCHAIN variable to either GNU or IAR, for example like this:
make TOOLCHAIN=GNU

The build results will be placed in the top level build/application/configuration/toolchain directory. For example, when building the display-demo application using the configuration for the Xplain board and the IAR toolchain, the result will end up in the build/display-demo/xplain/IAR directory. By default, the build process is quite silent, only listing which files are being built, not the full command lines used to build them. To see the full commands, enable verbose mode by setting the environment variable V to 1:
make V=1

4.3 Programming and Running an Application

To program an application to a target chip, enter the appropriate application directory under the apps/ directory and type make program. This will build, if needed, and upload the firmware to the target. Choosing between different configurations is done using the CONFIG environment variable, similar as for building an application. Running the application on the target is done by running the make run target. Example: program display-demo application to the ATxmega128A1 chip on the Xplain board
cd apps/display-demo make CONFIG=xplain program

Some environment variables to select programming tool, hardware programmer and programmer port must to be set when the user programs the application to the target. Example: program display-demo application to the ATxmega128A1 chip on the Xplain board using avrdude as programming tool
make CONFIG=xplain AVR_PROGTOOL=avrdude \ CONFIG_PROGRAMMER=jtagicemkii CONFIG_PROG_PORT=usb program

7
8294A-AVR-04/10

 CONFIG The name of the configuration to program for, here the Xplain board. AVR_PROGTOOL The name of the programming tool to use for 8-bit AVR devices, here avrdude. For 32-bit AVR devices this is named AVR32_PROGTOOL and is typically set to avr32program. CONFIG_PROGRAMMER The name of the programmer to use, here the JTAGICE mkII is in use. The build system supports the following tools: avrdragon, avrone, avrisp, avrispmkii, jtagice and jtagicemkii. CONFIG_PROG_PORT The communication port the programmer is connected to the PC, here a USB port. Programmer port is typically one of the following: /dev/ttySn, /dev/ttyUSBn, comN or usb. To simplify the command line, users can add the environment variables specified above in a top level config.mk, see section 4.4.1 Top Level Configuration File on page 9.

4.4 Configuration
Each application must provide one or more configuration files for the build system. These are named config-CONFIG.mk for each supported board. CONFIG usually represents board name and sometimes board name in combination with a specific feature. Example: display-demo for Xplain
config-xplain.mk

All applications must provide a configuration file for the default board; configuration files for any other boards are optional. The configuration files may contain all kinds of Makefile variable definitions, but its primary purpose is to specify configuration variables. These variables are available both to the build system and to the source files, so they need to follow a few special rules: The variable name must begin with CONFIG_. The variable name must be followed by a = character and a value with no spaces in between. String values must be surrounded by double quotes. Boolean values must be either y or n. Integer values are expressed using any valid C syntax. During the build process, this file is used as a source for generating the autoconf.h file, which is included implicitly in all source files. The variables are converted as follows: Boolean variables set to y become preprocessor symbols defined as 1. Boolean variables set to n are not defined, so #ifdef can be used to test the value of boolean configuration variables. String and integer variables become preprocessor symbols defined as their respective literal values, including the quotes for string variables. 8

AVR1913
8294A-AVR-04/10

AVR1913
There are also similar configuration files for each supported board, chip, CPU and architecture named config.mk and placed in the respective board-, chip-, cpu- and arch-specific subdirectories. These provide reasonable defaults which can be overridden by the application configuration file. 4.4.1 Top Level Configuration File To make build and programming commands simpler to type, the user can add a top level config.mk file and add the static defines shared between applications there. The top level config.mk.example file has all available defines documented and can be used as a template.

4.5 Optimization
Compiler and linker optimization is controlled through configuration symbols. By default, all files are compiled with maximum size optimization, but this can be customized on a per-application basis. To optimize for speed instead of size, set CONFIG_OPTIMIZE_SIZE to n. To select a different optimization level, set CONFIG_OPTIMIZE_LEVEL to the desired level (a number from 0 to 3). The following table summarizes the various possibilities. Table 4-1. GCC and IAR options from selected CONFIG_OPTIMIZE_SIZE and CONFIG_OPTIMIZE_LEVEL.
CONFIG_OPTIMIZE_SIZE y y y y n n n n CONFIG_OPTIMIZE_LEVEL 0 1 2 3 0 1 2 3 GCC option -Os -Os -Os -Os -O0 -O1 -O2 -O3 IAR option -z2 -z3 -z6 -z9 -s2 -s3 -s6 -s9

In addition, two forms of link-time optimizations are enabled by default when using the GNU toolchain. These are: CONFIG_RELAX: Link-time relaxation. Try to replace certain instructions by shorter alternatives. CONFIG_GC_SECTIONS: Link-time garbage collection. This will eliminate all functions and data items that aren't referenced. To disable any of those optimizations, set the corresponding configuration symbol to n.

9
8294A-AVR-04/10

4.6 Subdirectory Makefiles

Each subdirectory contains a Makefile fragment specifying which source files that is to be built into objects, and sometimes which additional subdirectories to include in the build. This Makefile fragment is usually called subdir.mk, but there are some exceptions to this rule: Application subdirectory Makefiles are named $(app).mk chip-, cpu-, arch- and board-specific Makefiles are named chip.mk, cpu.mk, arch.mk and board.mk respectively. The subdirectory Makefiles are usually very small, only appending to a single variable, obj-y, which specifies which objects to build, but there are other variables that may be altered by subdirectory Makefiles as well:
cppflags-toolchain-y - C preprocessor flags for all files cflags-toolchain-y - C compiler flags for all files ldflags-toolchain-y - Linker flags for the final link ldlibs-toolchain-y - Libraries to include in the final link

The reason why all these variables have the suffix -y is to make it easier to support conditional compilation and conditional flags. For example, if a certain object is to be built only when CONFIG_USB is set to y, this can be achieved as follows:
obj-$(CONFIG_USB) += drivers/usb/usb.o

10

AVR1913
8294A-AVR-04/10

AVR1913
4.7 Makefiles Provided by the Application
4.7.1 The Top-level Application Makefile Each application found under the apps/ subdirectory contains its own top-level Makefile which can be used to build that particular application. It is usually very simple, delegating the vast majority of the work to the build system core. Example: apps/display-demo/Makefile
src app DEFAULT_CONFIG DEFAULT_TOOLCHAIN := ../.. := display-demo := xplain := GNU

include $(src)/make/app.mk

The following variables must be defined by the top-level Application Makefile: src - The relative path to the top-level source directory app - The name of the application. $(src)/apps/$(app) must resolve to the directory in which the Makefile resides. DEFAULT_CONFIG - The name of the configuration to build for when the user doesn't specify any particular configuration. DEFAULT_TOOLCHAIN - The toolchain to use when the user doesn't specify any particular toolchain, either GNU or IAR. After defining these variables, the Makefile should simply include $(src)/make/app.mk to take care of the rest. 4.7.2 Application Subdirectory Makefile The application must include a file named $(app).mk specifying any applicationspecific object files and flags. This file follows the syntax described in section 4.6 Subdirectory Makefiles on page 10.

11
8294A-AVR-04/10

5 Display Xplained Application

The source code for the Display Xplained demonstration application is in the compressed file archive accompanied this application note.

5.1 Download, Compile and Program

The following step by step guide will reconstruct the original firmware for the Display Xplained board. 1. Download and uncompress the compressed file archive from www.atmel.com/products/AVR -> Application Notes -> AVR1913 Display Xplained Firmware Getting Started containing the Display Xplained source code. 2. Open up your favorite command line console and change into the directory extracted from the compressed file archive. 3. Enter the apps/display-demo directory. 4. Compile the application by telling the build system what kind of configuration you would like to use. This is done by setting the CONFIG symbol. For additional help, type make help on the command line. See the example below for how to compile for the Xplain board:
make CONFIG=xplain

5. The applications output binaries will be in the top level build/displaydemo/xplain/GNU directory. The display-demo.elf and display-demo.hex files are probably most interesting. If the user does not use the GNU toolchain, the GCC part of the path must be changed appropriately. Also, the board name must be changed if another configuration has been used. 6. Use your favorite programming software and tool to program the ELF or HEX file into the chip on the Xplain board. 5.1.1 Program the Application Using Avrdude In this example it is assumed the user has a JTAGICE mkII connected to the Xplain board. It is then possible to upload the display-demo.hex file to the ATxmega128A1 device using the following command:
make CONFIG=xplain PROGTOOL=avrdude \ CONFIG_PROGRAMMER=jtagicemkii \ CONFIG_PROG_PORT=usb program

For other programming tools the user must pass the appropriate arguments selecting the correct tool and communication port.

12

AVR1913
8294A-AVR-04/10

AVR1913
5.1.2 Program the Application Using AVR Studio 4 Users need to go through the following steps to program the display-demo.hex file using AVR Studio 4. First the connect dialog needs to be opened, this is done by clicking the button on the toolbar or select it from the Tools menu -> program AVR -> Connect Figure 5-1. AVR Studio connect dialog button on toolbar.

The connection dialog, as seen in the figure below, will pop up when clicking the previously mentioned connect dialog button. In the connection dialog the user must select the appropriate tool and port this tool is connected too. This example uses the JTAGICE mkII connected to the USB port. Figure 5-2. AVR Studio 4 connect dialog tool selection

13
8294A-AVR-04/10

Before starting to interface the device, the user must select the target device in the drop down menu on the Main tab. After the device is selected, the programming mode must be selected in the next drop down box. Then finally, verify that the connection is up and running by reading the device signature. Figure 5-3. AVR Studio 4 tool and device setup

14

AVR1913
8294A-AVR-04/10

AVR1913
The programming is done on the Program tab in the connect dialog window. It might be wise to do a chip erase first, to clear any lock fuses. This is done in the Device section of the Window. For programming, the user needs to point to where the HEX file is located. Click the small box at the end of Input HEX File field to open up a file browser and locate the display-demo.hex file. Finally hit the Program button to start programming the device. Success or failure can be observed in the status field at the bottom of the window. Figure 5-4. AVR Studio 4 tool hex file programming window

If the user experiences any issues when programming the device, it is highly recommend to consult the AVR Studio 4 help. This is located at the menu bar at Help -> AVR Tools Users Guide.

15
8294A-AVR-04/10

5.2 Upload Graphics to Xplain Board Flash Memory

It is assumed for this section that the Xplain board will have an USB mass-storage interface when connected to USB. For Xplain boards with an USB board controller, see section 6.1 Reprogramming the Xplain AT90USB1287 and ATxmega128A1 Firmware on page 22. For single chip Xplain boards or where the main chip controls the USB functionality, the display-demo firmware will enable the USB mass-storage functionality. In the directory /graphics/ in the archive file accompanying this application note, you will find the graphical bitmap files used in the display-demo application. The files are available in BMP and PNG formats, and the raw 16 bits per pixel image format suitable for the Display Xplained LCD. Located in the same directory is also a premade raw Tiny Simple file system (TSFS) image, which can be programmed directly into the flash memory of the Xplain board. More in-depth information about how to convert bitmaps and generate Tiny Simple file system images is in the following subchapters. 5.2.1 Precompiled Executables for Windows This chapter describes how to use the command line tools with the Python interpreter. On Windows systems, the precompiled executables may be used instead. These can be found in the /dist/ subdirectory for each tool. Note that the /graphics/ directory also contains two BAT-files that automate the tasks in this chapter: make_display_demo_fs.bat and write_display_demo_fs.bat. 5.2.2 How to Prepare Graphics for Display Xplained The compressed file archive contains a tool for converting graphics of various bitmap formats to the native format of the Display Xplained LCD controller. This tool is called bitmap2raw16bpp.py and is located in the directory /tools/bitmap-convert/. Instructions on how to use bitmap2raw16bpp.py is printed when executed without any arguments.
~ > python bitmap2raw16bpp.py usage: bitmap2raw16bpp.py [image file]

The tool will output a file with the same name as the input image file, but without any extension. The output file does not contain any metadata, e.g., height or width, and may be written directly to the Display Xplained LCD.

16

AVR1913
8294A-AVR-04/10

AVR1913
5.2.3 How to Generate a Tiny Simple File System Image File The archive also contains a tool for generating TSFS image files. This tool is called mkfs.tsfs.py and is located in the /tools/tsfs/mkfs.tsfs/ directory. Instructions on how to use mkfs.tsfs.py is printed when executed with the --help parameter.
~ > python mkfs.tsfs.py --help Usage: mkfs.tsfs.py [options] [files]

mkfs.tsfs.py will combine all the files listed in FILES into a Tiny Simple File System (TSFS) image file with a TSFS structure. By default mkfs.tsfs.py will write to 'out.raw', unless a file is specified by the -o option.

Options: -h, --help -o FILE, --output=FILE write TSFS image to FILE. Default is raw.out. show this help message and exit

For example, to generate a file system image for the DataFlash on the Xplain board with the desktop application, the syntax for mkfs.tsfs.py would look something like:
~ > python mkfs.tsfs.py o dataflash.img icon* picture* Generating Tiny Simple File System image... Completed: image file dataflash.img done, wrote 614976 bytes.

This would generate a dataflash.img file which is ready to be uploaded to the DataFlash on the Xplain board through the USB interface.

17
8294A-AVR-04/10

5.2.4 How to Upload a File System Image to Board Flash Memory The image created with the mkfs.tsfs.py tool must be uploaded to the Xplain board DataFlash memory for the display-demo application to be able to use the pictures, icons, etc. Since this file system image is a raw image it must be programmed directly to the USB mass-storage block device. The display-demo application does not support FAT and similar file systems. Since writing directly to block devices is vastly different between Microsoft Windows and Linux operating systems, there are two different descriptions of how to program the flash memory on the Xplain board below; one for each operating system. 5.2.4.1 Microsoft Windows Users The Microsoft Windows operating system does not have easy access to write directly to block devices. To ease this there is a tool in the /tools/tsfs/rawwrite/ directory called rawwrite.py. This tool is capable of writing a binary file directly to a block device. Instructions about how to use rawwrite.py is printed when executed with the --help parameter.
~ > python rawwrite.py help Usage: rawwrite.py [options] [file]

rawwrite.py will write the FILE file to a block device. When executed the application will scan the system for possible block devices and present them in a list. The user must then select the appropriate block device in the list. A final confirmation will be requested before continuing with the direct write to the block device.

Options: -h, --help show this help message and exit

Dangerous Options: Caution: this application writes directly to the block device, potentially destroying data already present on the device. If the user wrongly selects the block device used by the operating system installation the user will destroy vital data and possibly make the system unusable.

-e, --expert

Will list ALL the block devices on the system and let the user freely select the appropriate target and proceed with

the write.

18

AVR1913
8294A-AVR-04/10

AVR1913
For example, to write the dataflash.img file to the DataFlash on the Xplain board with the desktop application, the syntax for rawwrite.py would look something like:
~ > python rawwrite.py dataflash.img Scanning system for block device targets:

1) CBM Flash Disk USB Device (1028160 KB) Please select block device target [number]: 1

Are you sure you want to write '../tsfs/mkfs.tsfs/dataflash.img' to block device 'CBM Flash Disk USB Device'? [yes/no]: yes

Writing '../tsfs/mkfs.tsfs/dataflash.img' to block device 'CBM Flash Disk USB Device'... done

Verifying data on block device 'CBM Flash Disk USB Device'...

done

Write operation completed successfully.

This will write the dataflash.img file to the DataFlash on the Xplain board through the USB mass-storage interface. The rawwrite.py tool will not do any destructive operations until the user has given input to proceed with the write operation. This question is given while running the program. The rawwrite.py tool writes directly to the block device. If you do not select the correct block device from the device list, you risk destroying data on your computer. 5.2.4.2 Linux Users For Linux users there is a tool called dd which is capable of writing data directly to block devices. The dd application is usually part of the distributions core utils package. First off the user must identify which device node represents the Xplain board. After inserting the device the Linux system will probe the device and make the appropriate system nodes. This can be observed by typing dmesg:
usb 1-8.4: new full speed USB device using ehci_hcd and address 60 usb 1-8.4: configuration #1 chosen from 1 choice scsi4 : SCSI emulation for USB Mass Storage devices (...) sdc: unknown partition table sd 4:0:0:0: [sdc] Assuming drive cache: write through sd 4:0:0:0: [sdc] Attached SCSI removable disk

19
8294A-AVR-04/10

The previous operation reveals that the Xplain board is available as device node sdc, more specific the /dev/sdc device node in the root file system. The user can now write the TSFS image file to the block device node by using the dd command from the command shell:
dd if=dataflash.img of=/dev/sdc bs=512 oflag=sync

Note that this command will require super user access, depending on the distribution the user might need to su to the root user or prefix the command above with sudo to execute dd as super user. The dd application writes directly to the block device. If you do not specify the correct block device, you risk destroying data on your computer.

5.3 Using the Display Xplained Application

The application for Display Xplained will, when the steps mentioned earlier in this chapter are completed, start up and show an icon filled desktop, see figure below. By using the touch resistive film on the LCD the user can press the icons and start different applications. Figure 5-5. Display Xplained application desktop icons

To start the pictures application press the pictures labeled icon, see figure below. This will start an application much similar to a picture frame. Figure 5-6. Display Xplained application Pictures application on desktop

20

AVR1913
8294A-AVR-04/10

AVR1913
The picture viewer application will read pictures from the external flash memory and display them on the LCD panel. The resistive touch input can be used to skip forward and backwards by tapping close to the narrow edges of the screen. To exit the application, tap the center of the LCD. Figure 5-7. Display Xplained application picture frame input fields

A note regarding the display-demo application; it will not immediately be notified when a file has been copied to the flash memory or deleted. This means after filling the flash memory with images the user will have to eject the mass-storage device safely from the computers operating system and then reset the Xplain board. Images are assumed to be in 320 x 240 resolution and 16 bits per pixel, matching the LCD. All other pictures will be displayed, but those not matching the LCD specification will look distorted.

5.4 Documentation
The archive file for this application note also contains the technical documentation; indepth details of the implementation, drivers, protocols, libraries, code utilities and the display-demo application. It is located in the directory /documentation/display-demo/. Open the index.html file in any web browser to view the Doxygen style documentation. Doxygen is a tool for generating documentation from source code by analyzing the source code and using known keywords. For more details see www.stack.nl/~dimitri/doxygen.

21
8294A-AVR-04/10

6 Suggested Reading
6.1 Reprogramming the Xplain AT90USB1287 and ATxmega128A1 Firmware
For details about how to program either device on the Xplain board see the application note AVR1921: Reprogramming the Xplain AT90USB1287 and ATxmega128A1 Firmware. This describes how to program the devices using either a programming tool, like AVRONE!, JTAGICE mkII or AVR Dragon, or programming software, like FLIP. The application note is available from the www.atmel.com/dyn/products/tools_card_v2.asp?tool_id=4506. website at

6.2 Xplain Board Controller

For users with an Xplain board with multiple microcontrollers it is recommended to look into the AVR1922: Xplain Board Controller Firmware application note. This application note will describe how to compile and use the board controller on the Xplain board. The application note is available from the www.atmel.com/dyn/products/tools_card_v2.asp?tool_id=4506. website at

6.3 Xplain Board Getting Started

It is recommended to look into general usage of the Xplain board. This is covered in several application notes targeted for XMEGA devices available from http://www.atmel.com/dyn/products/app_notes_mcu.asp?family_id=607

22

AVR1913
8294A-AVR-04/10

AVR1913
7 Appendix A: Introduction to the UART Loopback Application
The uart-loopback application is a quite simple and basic use of the Display Xplained software framework. Its function is to setup the UART in software loopback mode, i.e. what is received on the RX line is read by the CPU and transmitted out on the TX line. When adding a new application to the software framework, like uart-loopback, the user needs to add the source code and some additional files related to how to build the source code and what to include from drivers, utilities and other included source code. This chapter will walk through the needed steps for adding the UART loopback application to give the user an idea of the basics of an application in the software framework. The source code for this appendix is included in the compressed file archive distributed along with this application note.

7.1 Application Directory

The new application needs to be added in a sub directory in the apps/ directory, for this example the apps/uart-loopback/ directory was chosen. It is short, concise and gives an idea of what the application is all about. In the application directory users must place all files specific for the application. This includes source files, header files, and configuration files and build-system files. Usually the application directory consists of at least the following files and directories:
apps/uart-loopback/Makefile apps/uart-loopback/config-xplain.mk apps/uart-loopback/include/app/version.h apps/uart-loopback/main.c apps/uart-loopback/uart-loopback.mk

More details about the different files in the following sections.

7.2 Application Source Code

Source code files should be placed in the application directory. In this example there is only a main.c file, which contains all of the functionality. Any header files should be placed in a sub directory include/app/ in the application directory. For the UART loopback application there is a simple version.h header file in the apps/uart-loopback/include/app/ directory.

23
8294A-AVR-04/10

7.2.1 Application Build System File In addition to physically adding the different source code files in the application directory, the application also needs to tell the build system about which files should be built, and which files are vital header files for the application. Informing the build system about what needs to be compiled is done through a Makefile. This must be placed in the application directory and named the same as the application. In the UART loopback application this file is located at apps/uartloopback/uart-loopback.mk. Example: apps/uart-loopback/uart-loopback.mk file
incdir-y src-y app-hdr-y hdr-y += $(src)/apps/$(app)/include += apps/$(app)/main.c += version.h += $(addprefix apps/$(app)/include/app/,$(app-hdr-y))

This will instruct the build system that the main.c file should be included in the list of source code files, the src-y variable. The application Makefile also defines the build systems application specific include directory, this is done by adding the directory to the include directory list, the incdir-y variable. Finally the version.h header file is added to the local variable app-hdr-y, which is then added, with the full path prefixed, to the global header list, the hdr-y, variable. The build system does now know about all needed source and header files for the application. When the user runs make the build system will compile and link the files listed in src-y, and pass incdir-y and hdr-y as compiler flags.

7.3 Application Makefile

The Makefile is the key file for the build system, and only needs a few defines and one inclusion of the base Makefile for the build system. See section 4.7.1 The Toplevel Application Makefile on page 11 for more details. Example: apps/uart-loopback/Makefile file
src app DEFAULT_CONFIG DEFAULT_TOOLCHAIN := ../.. := uart-loopback := xplain := GNU

include $(src)/make/app.mk

7.4 Application Configuration File

The application configuration file is responsible for various defines and inclusion needed by the application. This includes, but not limited to, defining which board to run the application on, which drivers to enable and various driver specific defines. For more details regarding the configuration file see section 4.4 Configuration on page 8. 24

AVR1913
8294A-AVR-04/10

AVR1913
Example: apps/uart-loopback/config-xplain.mk file
include $(src)/board/xplain/config.mk CONFIG_CPU_HZ=2000000UL CONFIG_SERIAL_UART=y CONFIG_UART_BAUD_RATE=9600 CONFIG_UART_ID=0

Initially the board configuration file is included, and then the CPU clock in Hz, CONFIG_CPU_HZ, is defined before the serial UART driver, CONFIG_SERIAL_UART, is enabled. In addition two defines setting the baud rate, CONFIG_UART_BAUD_RATE, and which UART ID, CONFIG_UART_ID, to use in the application for UART loopback. UART ID zero corresponds to the first instance of the USART modules on the chip, for the ATxmega128A1 this would be USARTC0. 7.4.1 Multiple Configurations Different configuration files can be loaded at build time by setting the CONFIG environment variable when calling make. For more information regarding multiple configuration files see section 4.4 Configuration on page 8. Example: uart-loopback application built for Xplain board controller (AT90USB1287)
make CONFIG=xplain-bc

Example: uart-loopback application built for Xplain main controller (ATxmega128A1)

make CONFIG=xplain

25
8294A-AVR-04/10

7.5 Building the Application and Run on Target

For building the application the user has to enter the application directory and use the make software required for the software framework. For the UART loopback application the user will have to run the following commands in a command line to compile for the ATxmega128A1 chip on the Xplain board:
cd apps/uart-loopback make CONFIG=xplain

This will result in an ELF file in the top level build directory at:
build/uart-loopback/xplain/GNU/uart-loopback.elf

Some environment variables must to be set when the user programs the ELF file to the target device, see section 4.3 Programming and Running an Application at page 7 for more details. Example: using avrdude as programming tool
make CONFIG=xplain AVR_PROGTOOL=avrdude \ CONFIG_PROGRAMMER=jtagicemkii \ CONFIG_PROG_PORT=usb program

The example above will program the uart-loopback application on the ATxmega128A1 chip on the Xplain board. To run the application the user must cycle power on the board.

26

AVR1913
8294A-AVR-04/10

Disclaimer

Headquarters
Atmel Corporation 2325 Orchard Parkway San Jose, CA 95131 USA Tel: 1(408) 441-0311 Fax: 1(408) 487-2600

International
Atmel Asia Unit 1-5 & 16, 19/F BEA Tower, Millennium City 5 418 Kwun Tong Road Kwun Tong, Kowloon Hong Kong Tel: (852) 2245-6100 Fax: (852) 2722-1369 Atmel Europe Le Krebs 8, Rue Jean-Pierre Timbaud BP 309 78054 Saint-Quentin-enYvelines Cedex France Tel: (33) 1-30-60-70-00 Fax: (33) 1-30-60-71-11 Atmel Japan 9F, Tonetsu Shinkawa Bldg. 1-24-8 Shinkawa Chuo-ku, Tokyo 104-0033 Japan Tel: (81) 3-3523-3551 Fax: (81) 3-3523-7581

Product Contact
Web Site http://www.atmel.com/ Technical Support avr@atmel.com Sales Contact www.atmel.com/contacts

Literature Request www.atmel.com/literature

Disclaimer: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN ATMELS TERMS AND CONDITIONS OF SALE LOCATED ON ATMELS WEB SITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and product descriptions at any time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive applications. Atmels products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life.

2010 Atmel Corporation. All rights reserved. Atmel , logo and combinations thereof, AVR , AVR logo, AVR Studio and others, are the registered trademarks; others are trademarks; XMEGA and others are trademarks of Atmel Corporation or its subsidiaries of Atmel Corporation or its subsidiaries. Windows and others are registered trademarks or trademarks of Microsoft Corporation in the US and/or other countries. Other terms and product names may be trademarks of others.

8294A-AVR-04/10