Getting started with emWin
With comprehensive documentation, pre-configured templates, and tools such as the AppWizard, emWin simplifies GUI development for a variety of applications. Developers can get started with emWin by integrating the library into their projects, utilizing sample code and ready-to-use widgets for faster prototyping and implementation. Whether working with a licensed microcontroller or evaluating the trial version, emWin offers flexibility and scalability to meet diverse project requirements.
Adding emWin to the target program
Developers have a choice between including only the source files that are actually going to be used in a project, (which will then be compiled and linked), or creating a library and linking to the respective library file. If the tool chain used supports "smart" linking (linking in the modules that are referenced and not linking in those that are not referenced), then there is no real need to create a library at all, since only the required functions and data structures will be linked.
If the tool chain does not support "smart" linking, use of a library makes sense, because otherwise all files will be linked and the program's size will be excessively large. For some CPUs, SEGGER has example projects available to help users get started. Generally speaking, all core emWin C files, the display driver, all font files used, and any optional modules ordered with emWin must be included.
Configuring the software
Before emWin can be used on a target system, the software needs to be configured. Configuration means modification of the configuration files that usually reside in the configuration sub directory. Effort has been made to keep the configuration as simple as possible, but there are some configuration routines that need to be modified in order for the system to work properly.
The following items need to be configured:
- Memory area to be used by emWin
- Display driver to be used for drawing operations
- Color conversion routines to be used
- Display controller initialization
- Hardware acceleration
Memory area to be used by emWin
emWin uses its own memory management system. Therefore, a memory block must be dedicated to emWin. Whenever emWin needs memory, it allocates it from this memory block.
Typically this is done by declaring a static array and passing its address to emWin. The array can be located in internal RAM or external RAM.
Within the function GUI_X_Config(), the user can use GUI_ALLOC_AssignMemory() to pass the memory address to emWin. This could look like this:
#if (defined __SES_ARM) // SES
static U32 aMemory[GUI_NUMBYTES / 4] __attribute__ ((section (".SDRAM1.GUI_RAM")));
#else
static U32 aMemory[GUI_NUMBYTES / 4];
#endif
void GUI_X_Config(void) {
//
// Assign memory to emWin
//
GUI_ALLOC_AssignMemory(aMemory, GUI_NUMBYTES);
}
Display driver
emWin always requires a display driver. This driver determines how to write into the frame buffer (GUIDRV_Lin driver) or how to communicate with a display controller (e.g. GUIDRV_FlexColor).
Typically this is done within the file LCDConf.c.
A detailed description on how to initialize a driver can be found here:
Color conversion
The color conversion defines how emWin writes pixel data to the frame buffer or sends it to a controller.
The selection of the color conversion is closely linked to the used driver and is also done in the file LCDConf.c. Please also refer to the examples for setting up display drivers.
Display controller initialization
The initialization of the display controller is not directly part of emWin. Therefore it can be done before calling GUI_Init(). However, a good place to initialize the display controller is the display driver callback function LCD_X_DisplayDriver(), which is usually located in LCDConf.c. Before any pixel operation is performed, emWin sends a LCD_X_INIT command to the callback function. The user can react to this command and initialize all necessary hardware components, such as the display controller itself, but also possible GPIOs.
Please refer to the examples mentioned above.
Hardware acceleration
emWin also offers an interface for routing drawing operations to a possible GPU. This is also done during driver setup and is most likely located in the file LCDConf.c.
Since this is quite hardware-dependent, we recommend to take a closer look at the configuration files provided with our evaluation packages. For example for the STM32H745 Discovery board which can be found here: https://www.segger.com/evaluate-our-software/st-microelectronics/#st-stm32h745-discovery
Writing applications
Once emWin is completely configured you can start to write you own application. emWin comes with an extensive collection of samples and tutorials that can easily be used as starting point. The typical "Hello World" application, for example, looks like this:
MainTask(void) {
GUI_Init();
GUI_DispString("Hello World!");
while (1) {
GUI_Delay(5);
}
}
For examples on a wider range of different topics please take a look into the emWin Examples.