emWin Graphics Library and GUI for PSoC™
emWin is an embedded graphic library and graphical user interface (GUI) framework. It provides an efficient, processor- and display-controller-independent graphics platform for applications that need a display. Examples include home appliances as well as automotive, IoT, and industrial applications. emWin is compatible with single-task and multitask environments. Developed by SEGGER Microcontroller, emWin is extremely popular in the embedded industry. CYPRESS™ has licensed the emWin library from SEGGER and offers it free to PSoC™ customers.
emWin can be used with PSoC™ 3, PSoC™ 4, PSoC™ 5LP, and PSoC™ 6 MCUs. Supported features vary as shown in the table.
The block diagram below shows the high-level details of how emWin integrates into an application.
emWin Library has two parts, the GUI framework and the display drivers. The GUI framework has functions like displaying text, bitmap images, widgets and drawing 2D graphics (lines, rectangles, circles etc). The display drivers interface with different types of display controllers. Peripheral drivers are the hardware interface to the display like SPI, UART, parallel interface, etc. The application layer implements Port API functions that control the hardware interface and perform operations like command write, single byte data write, multiple byte data writes, etc. The emWin display driver uses these functions to communicate with the display. The application layer allocates display memory that is used by the display driver. The application layer uses the functions provided by the emWin GUI framework to perform graphic operations on the display.
The block diagram shows the emWin design flow. Some of these steps may be optional depending on the device family and design platform.
1) Select emWin core: emWin supports various combinations of OS and Touch support. The method to select the option for different platforms can be found in the respective Getting Started documentation.
2) Select display driver: The list of display drivers and display controllers supported by these drivers can be found in the emWin user guide. From the user guide, select the display driver.
3) Copy library and configuration files: Depending on the selected core option and display driver, copy the relevant files into the project.
4) Port APIs and display configuration: Write Port API functions to communicate with the display and update emWin’s Port access functions with pointer to these functions. Configure display parameters like number of pixels, orientation, color profile, number of bits per pixel etc. in emWin’s configuration file.
5) Application code: In application code, call emWin’s graphic functions to draw graphics.
Code Examples: emWin Code Example Github Repositories
- For PSoC 6 device families, emWin code examples are distributed via Github and are accessible directly through the ModusToolbox project creator.
emWin Software: emWin Middleware Github Repository
- For PSoC 6 device families, emWin is provided as a middleware package for ModusToolbox™ and can be integrated using the library manager.
- With ModusToolbox™ Tools package installed, use the library manager application or CLI to create a local copy of an mtb-example-psoc6-emwin application.
- If using an emWin code example that supports AppWizard, the AppWizard_GUI\AppWizard_GUI.AppWizard file located in the code example directory can be opened within AppWizard and changes exported back to the project directory.
- Refer to the emWin and AppWizard User Guide & Reference Manual within the application directory under the emWin/doc subdirectory.
emWin User Guide:
Details on graphic APIs, features and display drivers may be found in the emWin User Guide & User Manual.
- ModusToolbox™ : emwin\<version>\docs\UM03001_emWin5.pdf
AppWizard User Guide & User Manual:
Details on graphical development tool AppWizard may be found in the AppWizard User Guide & Reference Manual.
- ModusToolbox™: emwin\<version>\docs\UM03003_AppWizard.pdf
Development Tool: PSoC™ Creator
Code Examples: PSoC™ Creator Code Examples
emWin Software: SEGGER emWin Graphic Library
- emWin is provided as a library package that can be manually included in a project.
- This package has the limited feature 8051 library for PSoC™ 3 and the full feature library for PSoC™ 4 and PSoC™ 5LP. This library can be used with Keil_PK51, GCC, and Keil MDK toolchains.
Getting Started: Once installed in the default location, the Getting Started information can be found in the following location.
<PDL Installation Folder>/doc/pdl_api_reference_manual.html
emWin User Guide:
Details on graphic APIs, features and display drivers may be found in the emWin User Guide. The user guide may be found in the following folder when the emWin v5.46 package (emWinGraphics_v5_46.zip) is unpacked.
- PSoC™ 3: emWinGraphics_v5_46\Documentation\PSoC3\UM03002_emWin_8051.pdf
- PSoC™ 4 & PSoC™ 5LP: emWinGraphics_v5_46\Documentation\PSoC4_5\UM03001_emWin5.pdf
The Bitmap Converter converts common image file formats like BMP, PNG or GIF into the desired emWin bitmap format. That can be a C file that can be compiled and linked with the project, or a binary format that can be loaded at runtime. Simply load an image into the application. Convert the color format if necessary and save it in the appropriate format.
The emWin viewer allows viewing the display output while stepping through (debugging) the simulation. The display output normally could not be seen while stepping through code. When the debug thread is halted, all other threads of the process are also halted. This includes the thread that outputs the simulated display on the screen.
The GUIBuilder application is a tool for creating dialogs. Instead of writing source code the widgets can be placed and sized by drag and drop. Additional properties can be added by context menu. Fine tuning can be done by editing the properties of the widgets. This does not require any knowledge of the C programming language. The dialogs can be saved as C files which can be enhanced by adding user defined code.
In ModusToolbox™, the tools are located in the following application folders under /emWin/<version>/Tool subdirectory
The emWin User Guide has information on how to use these tools. Location of emWin User Guide may be found in the Getting Started tab
GUI Development Tools
AppWizard is a desktop application for creating complete, ready-to-run applications for use with the emWin embedded graphics library. AppWizard features an intuitive “What You See is What You Get” (WYSIWYG) editor and provides its own built-in resource management capabilities. It facilitates the use of all of emWin's core functions, such as the rendering of animations, language management, widgets, etc.
AppWizard is available for download from the online Infineon Develop Center for use with PSoC devices