Installing And Using emWin On A PSoC

emWin is a graphical user interface designed for embedded systems. Cypress provides a free emWin license when you use the PSoC IDE. If I directly quote from the SEGGER website:

emWin is designed to provide an efficient, processor- and LCD controller-independent graphical user interface (GUI) for any application that operates with a graphical LCD.

I want to make and amendment here as say that you can use emWin for not just LCD displays, but any display which is controlled via pixel information (such as OLED displays). You do not have access to the emWin source code, instead you are given a pre-compiled object file, headers, and source code only for the port-specific functions. Unfortunately, the graphics library is not provided as a quick-and-simple PSoC component which can be drag ‘n’ dropped onto the schematics in PSoC Creator. Instead, you have to download the code library as a zip file, and manually install it.

Installing In PSoC Creator

The installation procedure is slightly different depending on whether you are using Keil (PSoC 3) or GCC (PSoC 4, 5, 5LP) to compile

Keil (PSoC 3) Specific Steps

Make sure you add the emWin link library (emWinnosnts.lib, emWinnosts.lib or similar) to the linker, otherwise you will get unresolved reference errors, even if you’ve added all of the .c and .h files to the project. This is not an obvious step! These are added by navigating to Build Settings->Linker->Additional Link Files in PSoC Creator.

GCC (PSoC 4, 5, 5LP) Specific Steps

Right-click on your project, and select Build Settings. Navigate to ARM GCC x.x.x->Linker->General and fill in the Additional Libraries and Additional Library Directories fields similar to as shown in the image below. Note that in the Additional Libraries field, you are referencing the file in a directory that is specified in the Additional Library Directories field, however, the “lib” prefix and “.o” file extension have to be removed. This is the standard GCC way of naming and specifying libraries.

The linker build settings for using emWin with GCC.

The Functions You Have To Write Code For

There are a few port-specific functions that you have to write code for, before emWin will work properly. These functions concern reading/writing to the output buffer that the image data will be written to. These are:

• CYGRAPHICS_WRITE()
• CYGRAPHICS_READ()
• CYGRAPHICS_IS_VBLANKING()
• CYGRAPHICS_WRITE_FRAME()

If you just want basic control, the only function you have to write code for is CYGRAPHICS_WRITE(). The rest can be left blank.

Setting The Draw Position

The draw position can be set with GUI_GotoXY(x, y), where x in the x-axis position, and y is the u-axis position (both measured in pixels). The draw position is incremented automatically when commands that place strings of text are used.

Fonts

Available Fonts

Only some of the fonts listed in the emWin manual are available in the PSoC version. These include proportional fonts such as monospaced fonts such as GUI_Font4x6, GUI_Font8x8.

Using Fonts

To start using a font, type the command:

GUI_SetFont(&GUI_Font4x6);

This will use the font from this point onwards, until GUI_SetFont() is called again.

Displaying Text

You can display text with the function GUI_DispString(char* msg);, where msg is a pointer to an array of null-terminated characters that you want to print. For example:

// Display a string of text
GUI_DispString("This is a message!");