Creating a basic GUI application with Synergy and GUIX SK-S7G2

Creating a basic GUI application with Synergy and GUIX SK-S7G2 LAB PROCEDURE Description: The objective of this lab session is to detail the process of creating an embedded graphics user interface, starting with getting the display hardware configured, then outputting an image to the display, adding data output, and user input through the touch panel. Lab Objectives 1. Learn how to set up a display 2. Create a splash screen using GUIX Studio 3. Integrate GUIX elements into a Synergy project 4. Set up and test a basic Graphical User Interface (GUI) Skill Level 1. Familiarity with e2studio and debuggers 2. Project creation with Synergy SSP configuration tool Lab Materials Please verify you have the following materials at your lab station. e2 studio v5.3.1.002 GNU Tools for ARM (gcc-arm-noneeabi-4_9-2015q3-20150921) Synergy SSP v1.2.0 with current license GUIX Studio v5.3.2.2 Synergy SK-S7G2 Starter Kit board USB Type A to Micro-B cable Time to Complete Lab 100 Minutes Lab Sections 1 Project Creation... 2 2 LCD Panel configuration... 6 3 LCD Panel interface setup... 10 4 Build a GUI using GUIX Studio... 16 5 Adding GUIX Framework and Drivers... 19 6 Add a Data Output Window to the GUI... 21 7 Add Messaging Framework and Touch Drivers... 23 8 Add an Input Button to the GUI... 27 Creating a basic GUI application with Synergy and GUIX Page 1 of 28

1 Project Creation Overview: In this lab section, we will create a thread that initializes the GUI system and handles user events. Procedural Steps: LAB PROCEDURE Launch e2 studio and specify a Workspace location that does not yet exist (empty workspace) such as C:\Workspace\synergy_gui_lab Note: If you specify another workspace path than shown, be sure to adjust for that later in the lab where the path is referenced. Close the Welcome window or click Workbench. In e 2 studio, go to File > New. Select Synergy C Project. The Project Configuration dialog will appear. Creating a basic GUI application with Synergy and GUIX Page 2 of 28

In the Project Configuraton window name the project my_gui_app Note: Throughout this lab we will name your newly created components with "my_" prefix to easily distinguish them from Synergy system labels. If a license has not yet been specified, click the Change license file link, then, then Browse as shown below to select a license file. Creating a basic GUI application with Synergy and GUIX Page 3 of 28

Ensure that GCC ARM Embedded is selected as the Toolchain, then click Next. Select S7G2 SK in the Board drop-down list and leave the other options as default. Click Next. Press the radio button BSP in the Project Template Selection menu. Click Finish. e 2 studio will create the S7G2-SK BSP project for you. Select the Threads tab on and click the New Thread button. Creating a basic GUI application with Synergy and GUIX Page 4 of 28

You will find a thread named New Thread appeared in the Threads pane. Change the Name of the thread to My GUI Thread in the Properties view. Change the Symbol of the thread to my_gui_thread as well and change the priority to 10. Click the Generate Project Content button on the Synergy Configuration view to generate the thread. You should find the following files have been generated by the Synergy Configurator. Build the project and make sure there are no errors. Creating a basic GUI application with Synergy and GUIX Page 5 of 28

2 LCD Panel configuration LAB PROCEDURE Overview: In this lab section, we will investigate the hardware settings for the LCD panel and configure the display driver to make sure the low level layers of the GUI system work properly. Procedural Steps: Click My GUI Thread in the Threads pane and confirm it gets highlighted. Then click the New Stack button in the My GUI Thread Stacks pane to select GUIX on gx from the X-Ware->GUIX drop-down. Click on the g_display0 Display Driver on r_glcd in the My GUI Thread Stacks pane and the configuration parameters are shown in the Properties view. Creating a basic GUI application with Synergy and GUIX Page 6 of 28

Edit the Display Driver properties for the LCD panel for the SK-S7G2 board as shown. This time we should only need to change the yellow highlighted properties in Table 1, however check the other settings just in case they got changed. Table 1 Synergy Configuration settings for Display Driver on r_glcd Type Display on GLCD Properties Value Description General Name g_display0 The name of the display device instance (Please use this name for this lab) Name of display callback function to be defined by user NULL The name of the user display interrupt callback function Input Panel clock source select Internal clock Internal GLCDC-generated clock signal Graphics screen1 Graphics screen1 frame buffer name Number of Graphics screen1 frame buffer Section where Graphics screen1 frame buffer allocated Graphics screen1 input horizontal size Graphics screen1 input vertical size Graphics screen1 input horizontal stride Used fb_background The suffix to the frame buffer array name. The full name is defined as [module_name]_[fb_name] in this case, g_display0_fb_background 2 Ping-pong buffer system needs two frame buffers to avoid tearing bss bss (internal SRAM) is used for the frame buffers 256 Width of frame buffer in pixels (must be multiple of 64 bytes, or 32 pixels @16bpp) 320 Height of frame buffer in pixels 256 Length of a row of pixels (in pixel units). Except in rare cases this will always be set the same as horizontal size. Graphics screen1 input format 16bits RGB565 Framebuffer pixel format Graphics screen1 input line Not used descending Graphics screen1 input lines repeat Off Graphics screen1 input lines repeat times is ignored. Graphics screen1 input lines 0 repeat times Graphics screen1 layer 0 coordinate X Graphics screen1 layer 0 coordinate Y Graphics screen1 layer 255 background color alpha Graphics screen1 layer 255 background color Red Graphics screen1 layer 255 background color Green Graphics screen1 layer 255 background color Blue Graphics screen1 layer fading control None Graphics screen1 layer fade speed is ignored. Input - Graphics screen1 layer 0 fade speed Graphics screen2 Not used All the Properties for Graphics screen2 are ignored. Output Horizontal total cycles 320 Total number of active lines on the screen (same as vertical size) Creating a basic GUI application with Synergy and GUIX Page 7 of 28

Horizontal active video cycles 240 Total number of active pixels per line (same as horizontal size) Horizontal back porch cycles 6 Horizontal back porch Horizontal sync signal cycles 4 Horizontal sync (Hsync) assertion length Horizontal sync signal polarity Low active Vertical total lines 328 Total number of lines to output (including blanking interval) Vertical active video lines 320 Total number of active lines per frame (same as vertical size) Vertical back porch lines 4 Vertical back porch Vertical sync signal lines 4 Vertical sync (Vsync) assertion length Vertical sync signal polarity Low active Format 16bits RGB565 Output pixel format Endian Little endian Color order RGB Data Enable Signal Polarity High active DE (High active) Sync edge Rising edge Same above Background color alpha 255 channel Background color R channel 0 Background color G channel 0 Background color B channel 0 CLUT Not used CLUT buffer size (don t care) TCON Hsync pin select LCD_TCON2 Hsync signal Vsync pin select LCD_TCON1 Vsync signal DataEnable pin select LCD_TCON0 Data Enable (DE) signal Panel clock division ratio 1/32 Divisor for panel clock Color correction Brightness Off All the brightness settings are ignored. Contrast Off All the contrast settings are ignored. Gamma correction(red) Off All the gamma correction settings for Red are ignored. Gamma correction(green) Off All the gamma correction settings for Green are ignored. Gamma correction(blue) Off All the gamma correction settings for Blue are ignored. Dither Dithering Off All the dither settings are ignored. Misc. Correction Process Order Brightness and Contrast then Gamma Interrupts Line Detect Interrupt Priority Priority 3 Vsync interrupt Underflow 1 Interrupt Priority Priority 3 Generally only caused by bus congestion Underflow 2 Interrupt Priority Disabled Creating a basic GUI application with Synergy and GUIX Page 8 of 28

Now click on the g_jpeg_decode0 JPEG Decode Driver on r_jpeg in the My GUI Thread Stacks pane and set the interrupt priorities to 3. Click on the D/AVE 2D Port on sf_tes_2d_drw in the My GUI Thread Stacks pane and set the DRW INT priority to 3. Creating a basic GUI application with Synergy and GUIX Page 9 of 28

3 LCD Panel interface setup LAB PROCEDURE Overview: The LCD on the SK-S7G2 has both parallel and serial (SPI) interfaces. By default on the SK-S7G2 the LCD interface mode has been configured to start up in the SPI interface mode in order to initialize the display driver IC before use. As a result, we need to set up a SPI communications interface with SSP. In this lab section we will add an RSPI driver and configure pins for the SPI bus. Procedural Steps: Click My GUI Thread in the Threads pane and confirm it gets highlighted. Then click in the My GUI Thread Stacks pane to select SPI Driver on r_rspi from the Driver->Connectivity drop-down list. Creating a basic GUI application with Synergy and GUIX Page 10 of 28

LAB PROCEDURE Click on the g_spi0 SPI Driver on r_rspi module and edit the settings as shown below in the Properties view. Select the g_transfer0 Transfer Driver on r_dtc in the My GUI Thread Stacks pane and press Remove to remove the driver. Repeat the previous step for the g_transfer1 Transfer Driver on r_dtc. The RSPI driver can currently only support DTC transfer of 32 bit words. We need to send individual bytes over SPI so we must disable the DTC drivers for the g_rspi_lcdc SPI Driver. Creating a basic GUI application with Synergy and GUIX Page 11 of 28

The RSPI bus pins need to be configured. Go to Synergy Configuration and open the Pins tab. Find Peripherals Connectivity:SPI, and expand the list. Select SPI0 and change the Operation Mode to Enabled. Ensure that the pin assignments are as shown below. Creating a basic GUI application with Synergy and GUIX Page 12 of 28

Several LCD panel signals are controlled by GPIO pins under application control. Because the RSPI is configured for Clock Synchronous operation the SPI slave select signal must be controlled by the application as a GPIO pin. Slave select for the LCD is on P611. Additionally there is a reset pin on P610 and a command pin on P115. We need to enable these three pins as GPIO outputs. Only P610 is shown below apply the same settings to P611 and P115. Click the Generate Project Content button on the Synergy Configuration view. This will add the new display driver and RSPI configuration settings to your "my_gui_thread.c" and "my_gui_thread.h generated files. Synergy does not have built-in LCD startup files specific to the SK display, so we have borrowed the various necessary pieces of code from a previous project to help you with the display startup. Copy the provided files lcd_setup.c and lcd.h into your project src folder. Creating a basic GUI application with Synergy and GUIX Page 13 of 28

The LCD setup code uses a semaphore that you will need to create. Return to the Synergy Configuration view Threads tab and select the My GUI Thread thread. Then locate the My GUI Thread Objects pane and click the New Object button to create a new semaphore. Select the new semaphore g_new_semaphore and change its Name and Symbol in the properties tab to My GUI Semaphore and g_my_gui_semaphore. These names match the values already used in the lcd_startup.c code. Copy the provided file my_gui_thread_entry.c to the src folder in your e 2 studio project (overwrite the existing file). The provided code opens and starts the Display interface to drive the LCD panel. Build the project and make sure there are no compile errors. Connect the Micro USB end of the supplied USB cable to the SK-S7G2 board J19 connector (DEBUG_USB), and the other end to a USB port on your computer. (J19 connects to a SEGGER J-Link On-Board debugger.) Creating a basic GUI application with Synergy and GUIX Page 14 of 28

Click the button pull-down and select Debug Configurations. Check that the debugger configuration is same as below, then click the Debug button to connect debugger to the target board. Run the program and make sure the LCD panel is activated. There should be 3 color bars on the LCD panel that are drawn directly into the frame buffer by the test_lcd() function. After initializing the LCD, the program should be in while(1) loop in the my_gui_thread_entry() function. Creating a basic GUI application with Synergy and GUIX Page 15 of 28

4 Build a GUI using GUIX Studio LAB PROCEDURE Overview: In this section you will create a new GUIX Studio Project, set it up for the LCD on the SK-S7G2 board, assign a 'splash screen' and then output the files generated by GUIX Studio into your Synergy project. Procedural Steps: Open GUIX Studio and click Create New Project at the startup screen. Enter a Project Name for this GUIX Studio project. This name will be incorporated into the code generated, so for this lab name it "my_guix_lab" (do not change this or you will have to change all the references to it in the provided Synergy project code). Locate the path for your Synergy GUI lab project, enter it as the Project Path, then click Save. (Note: This is the full path to your Synergy project, not just the workspace name.) Set the paths for GUI source files to be generated. For this lab we want them to go in the src folder. Set all other values as shown, then click Save: Creating a basic GUI application with Synergy and GUIX Page 16 of 28

LAB PROCEDURE Note! You may be tempted to change the x resolution setting to 240 to match the number of pixels per line of the SK display, but don't! The Synergy display driver requires a screen width divisible by 64 bytes at 16 bits per pixel that s 32 pixels. This is due to the way the GLCDC peripheral internally performs burst transfers. That aside, your display image file size still needs to be limited to 240 x 320 to display properly without being cut off. From the Project View, right-click main_display and select Insert->Window->Window: In the Properties View for the newly created window set the properties as shown: Creating a basic GUI application with Synergy and GUIX Page 17 of 28

Now we need to add the splash screen graphic. We'll use a.jpg image file that has already been sized for this LCD display. In the upper-right of GUIX Studio expand the Pixelmaps view, click Custom, then Add New Pixelmap. The image file selector will open. Locate the provided file "splash_screen.jpg" and select it. The "splash_screen.jpg" file will now be available in the Custom pixelmaps view. You can either click on this and drag/drop it into your splash screen window in the preview area or select it from the Wallpaper pull-down in the splash_screen Properties View: At this time we will save the project and output the GUIX screen to your Synergy project. Click Project- >SaveProject. Next click Project->Generate All Output Files, then Generate. GUIX will add the following files to the src folder in your Synergy project: my_guix_lab_resources.c, my_guix_lab_resources.h, my_guix_lab_specifications.c and my_guix_lab_specifications.h. Creating a basic GUI application with Synergy and GUIX Page 18 of 28

5 Adding GUIX Framework and Drivers LAB PROCEDURE Overview: In this section you will use the SSP to configure the framework and drivers in your Synergy project that are needed to access GUIX resources in order to output the GUI to the LCD. Procedural Steps: In the Synergy configurator under the Threads tab select My GUI Thread. In the My GUI Thread Stacks pane select the GUIX on gx module and enable the 2D Drawing Engine and JPEG Support. In the My GUI Thread Stacks panel now select g_sf_el_gx0 GUIX Port on sf_el_gx then change its settings in the Properties tab as shown below: Click the Generate Project Content button on the Synergy Configuration view to generate the new driver code. Add the provided file my_gui_event_handler.c to the src folder. In the Project explorer view locate the source file my_gui_thread_entry.c and open it in the editor. Enable sections of code by editing the following lines: Line 4 #define LCDTEST 1 Change 1 to 0 Line 5 #define GUIX 0 Change 0 to 1 Build the project and make sure there are no compile errors. If you get errors related to D/AVE files ( Secure builder required ) right click on your project and select Clean Project then build again. Creating a basic GUI application with Synergy and GUIX Page 19 of 28

Click the button to run the project under the Debugger. At this point the LCD should be displaying the splash screen graphic and the program should be idling in the main while(1) loop. Creating a basic GUI application with Synergy and GUIX Page 20 of 28

6 Add a Data Output Window to the GUI LAB PROCEDURE Overview: In this section you will use GUIX Studio to add a text window to your GUI, and send a custom message string to it. This is the basis for outputting run-time data from an application to the GUI. Procedural Steps: If your GUIX Studio project you created in the previous section is not still open, open it now. This can easily be done from within e2studio by double-clicking the GUIX Studio icon in the Project Explorer view. Under the GUIX Studio Project View, add a Multi-Line View widget to the splash_screen by right-clicking, then Insert->Text->Multi Line View. In the GUI preview drag the newly created widget to the lower area and resize it to look like this: Creating a basic GUI application with Synergy and GUIX Page 21 of 28

Expand the Colors menu at the upper right and locate the entry for TEXT_INPUT_FILL. Double-click the color square next to it to open the color editor. Change the fill color to black by moving all sliders (or just the Luminance slider) to 0. Save the changes. The white text on black background should now be visible. In the Properties View for the Multi Line View widget, change the Text align property to Left and the Text property to "My initial text" or some other short string if you prefer. This is what will be displayed when the application starts up. Click Project->Save Project. Next click Project->Generate All Output Files, then Generate. GUIX Studio will modify the source files in your Synergy project with the new GUI changes. Go back to your Synergy project in e2studio and rebuild the project. Run your project in the debugger to see the new Text View displayed with your starting message. Creating a basic GUI application with Synergy and GUIX Page 22 of 28

7 Add Messaging Framework and Touch Drivers LAB PROCEDURE Overview: In this section you will add the Synergy Messaging Framework and Touch Drivers to allow interaction with the GUI. Procedural Steps: In the Synergy Configuration view Threads tab select the My GUI Thread. Then in the My GUI Thread Stacks add the Touch Panel & Messaging frameworks by selecting Panel Framework on sf_touch_panel_i2c. New->Framework->Input->Touch Select the newly-created g_sf_touch_panel_i2c0 Touch Panel Framework on sf_touch_panel_i2c and configure its settings in the Properties tab as shown below: In the Pins tab, set port 6 pin 9 (P609) to Output mode (Initial High). Creating a basic GUI application with Synergy and GUIX Page 23 of 28

In the Threads tab Select My GUI Thread on the Threads pane and click the Add I2C Driver box under the g_sf_touch_panel_i2c0 Touch Panel Framework. Select New->I2C Master Driver on r_riic: Now select the g_i2c0 I2C Master Driver on r_riic in the My GUI Thread Stacks pane and configure its settings in the Properties tab. Creating a basic GUI application with Synergy and GUIX Page 24 of 28

In the Pins tab verify that the RIIC I/O pins are enabled: Select g_external_irq0 External IRQ Driver on r_icu and configure its settings in the Properties tab as shown below. In the My GUI Thread Stacks pane click Add Touch Driver and select New->Touch Panel Driver on touch_panel_sx8654. Creating a basic GUI application with Synergy and GUIX Page 25 of 28

LAB PROCEDURE In the Synergy Configuration window select the Messaging tab and click on the Touch event class. In the Touch Subscribers pane press the New button and select My GUI Thread from the drop down list. Press OK. Click the Generate Project Content button on the Synergy Configuration view to generate the new driver code. In the Project explorer view locate the source file my_gui_thread_entry.c and open it in the editor. Enable sections of code to handle touch events by editing the following line: Line 6 #define TOUCH 0 Change 0 to 1 Next we will learn how to change the contents of the Text View window at runtime. For now, we will use the sample event handler that has been prepared for you. The event handler will change the text after a short time delay from start. From the src folder, open the file my_gui_event_handler.c in the editor. Uncomment lines 30 and 40 to enable the statements: GX_MULTI_LINE_TEXT_VIEW * my_text_view = &splash_screen.splash_screen_text_view_1;... status = gx_multi_line_text_view_text_set(my_text_view, "Hello World from Synergy!!!"); If you like, you can edit the string on line 40 to say something else. Since this argument takes a string literal or a pointer to a string, this can be adapted to handle all kinds of string output. For example, if you have numeric sensor data you could turn it into a string using the C sprintf() function then provide that as the string argument in gx_multi_line_text_view_text_set(). See the GUIX API user manual for further details. Rebuild the project and run it in the debugger to see the new customized message displayed after a short delay. Creating a basic GUI application with Synergy and GUIX Page 26 of 28

8 Add an Input Button to the GUI LAB PROCEDURE Overview: In this section you will use GUIX Studio to add an Input Button to the GUI and detect button presses in your Synergy application. Procedural Steps: If your GUIX Studio project is not still open, open it now. This can easily be done from within e2studio by double-clicking the GUIX Studio icon in the Project Explorer view. Under the GUIX Studio Project View, add a Text Button widget to the splash_screen by right-clicking, then Insert->Button->Text Button. (Be sure to add it to the splash screen, do not add it to the text box) Move the button to the center of the upper LCD area and resize it to make it larger. (If it's too small it may be hard to press on the small LCD.) In the Properties View for button_1 edit the Widget Id field to BUTTON1 Click Project->SaveProject. Next click Project->Generate All Output Files, then Generate. GUIX Studio will modify the source files in your Synergy project with the new GUI changes. Go back to your Synergy project. In my_gui_event_handler.c enable the case statement that handles this button by changing line 46 to #if(1). Creating a basic GUI application with Synergy and GUIX Page 27 of 28

Rebuild the project. Run your project in the debugger. After a short delay see the new Text View displayed with your starting message. Touch your GUI button on the LCD and watch for LED1 to turn off. Finished Creating a basic GUI application with Synergy and GUIX Page 28 of 28