SEGGER emWin Graphics Library

What is emWin?

emWin is an embedded graphic library and graphical user interface (GUI) framework designed to provide an efficient, processor- and display controller-independent GUI for any application that operates with a graphical display. It 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 for free to customers.

Supported Features

• 2-D Graphics Library
• Displaying bitmap files
• Fonts
• Memory Devices
• Multitask (RTOS)
• Window Manager
• Window Objects (Widgets)
• Virtual Screens / Virtual Pages
• Pointer Input Devices
  • Touch screen support (user defined)
  • Sprites and Cursors
• Antialiasing
• Language Support
  • Multi-codepages support
  • Unicode support
  • Right-to-left and bidirectional text support
• Display Drivers
  • BitPlains
  • CompactColor_16
  • FlexColor
  • Lin
  • SPage
  • Template
• Toolchains
  • GNU ARM Embedded v7
  • ARM Compiler v6
  • IAR v8

Using emWin in an Mbed project

1. Add emWin to the target project.

   mbed add https://github.com/cypresssemiconductorco/middleware-emwin

2. Decide, what emWin core option and display driver is required in your project:
   • Core option let you select required multitasking and touch support combination.
     • EMWIN_NOSNTS - No multitasking and no touch support
     • EMWIN_NOSTS - No multitasking support, touch support
     • EMWIN_OSNTS - Multitasking support, no touch support
     • EMWIN_OSTS - Multitasking and touch support
   • Display driver selection depends on the display controller used in the project. Please refer to Display drivers -> Available display drivers section of the emWin User Guide for detailed list of supported display controllers by each driver.
3. Enable required core option by adding it to the mbed_app.json in the "target_overrides" section:

   {
   "target_overrides": {
           "*":{
               "target.components_add": ["EMWIN_NOSNTS"]
           }
       }
   }

4. Copy following emWin configuration files into the project from the emwin-middleware/Sample folder. It is recommended to keep all emWin config files in a separate folder located at the project directory. For example, the files may be copied to a folder named emwin_config in the root project folder.

   • emWin core configuration files:
     • GUI_X/GIU_X_Mbed.cpp
     • GUIConf/GUIConf.c
   • emWin driver configuration files:
     • LCDConf/[selected_driver_name]/Generic/LCDConf.c
     • LCDConf/[selected_driver_name]/LCDConf.h

   If the project uses either the CompactoColor_16 or the Template drivers, following additional files have to be copied:

   • For CompactColor_16:
     • LCDConf/CompactColor_16/Generic/LCDConf_CompactColor_16.h
     • DisplayDriver/CompactColor_16/GUIDRV_CompactColor_16.c
     • DisplayDriver/CompactColor_16/GUIDRV_CompactColor_16.h
   • For Template driver:
     • DisplayDriver/Template/GUIDRV_Template.c
     • DisplayDriver/Template/GUIDRV_Template.h

5. Change config files extension - c to cpp:

   • GUIConf.c -> GUIConf.cpp
   • LCDConf.c -> LCDConf.cpp

   Note

   At this point you can test if all required files are present and correctly selected in the project. For that, place the following code in main.cpp and build the project.

   If steps above were done correctly, you will be able to successfully build the project:

   #include "mbed.h"
   #include "GUI.h"
       
   int main()
   {
       GUI_Init();
       
       for(;;)
       {
           
       }
   }

6. Modify the configuration files per application needs:

   • GIU_X_Mbed.cpp - provides emWin timing routines. This file is preconfigured to work with mbed-os, so no modifications are needed.
   • GUIConf.cpp - defines RAM size dedicated for emWin. By default, emWin needs 32 kB of RAM, which is enough for the basic applications. If needed, adjust the dedicated RAM size by changing value of the GUI_NUMBYTES macro.
   • LCDConf.cpp - defines display resolution, color conversion, initialization code and the callback function for the display driver. For the run time configurable drivers this file also configures the interface I/O functions to communicate with the display controller.
   • LCDConf.h - provide configurations for Template driver. No changes needed for other display drivers.

   CompactColor_16:

   • LCDConf_CompactColor_16.h - defines emWin display controller I/O functions and other configurations.

   For details on the emWin core configuration refer to Configuration section of the emWin User Guide.
   For details on the emWin display driver configuration refer to Display drivers -> Available display drivers section.

7. Implement I/O functions for the selected display driver. For the details, refer to emWin User Guide.
8. Write the initialization code for the display interface and the display driver controller in the _InitController() function of the LCDConf.c configuration file.
9. Include GUI.h header in your source file.
10. Call the GUI_Init() function to initialize emWin.
11. Call emWin graphic APIs to perform graphic functions in the project.

emWin Example Projects

Segger provides many code examples to demonstrate various features of emWin. These examples can be found in the Sample/Tutorial directory. To run an example:

1. Add one of the demo sample files to your project.
2. Configure emWin as described in the section above.
3. Edit the main source file (main.cpp) to include GUI.h and then call MainTask() as shown in the code that follows. All of the emWin examples use MainTask() as the entry point.

   #include "mbed.h"
   #include "GUI.h"
   
   int main()
   {
       MainTask();
       for(;;)
       {
           
       }
   }

4. Compile and run the project.

Changelog

Version	Changes	Reason for Change
5.48.0	Initial release with PSoC6 Mbed targets support	Mbed flow support