Microchip Graphics Suite (MGS) Simulator Button Example

Last modified by Microchip on 2024/05/31 15:40

Introduction

This guide shows how to develop a simple Button example using the Microchip ecosystem - Microchip Graphics Suite (MGS) Composer, MPLAB® X IDE, MPLAB Code Configurator (MCC), MGS Simulator.

To learn more about the MGS Composer, refer to the "Microchip Graphics Suite (MGS) Harmony Composer User Guide" page.

To learn more about the MGS Simulator, refer to the "Microchip Graphics Suite (MGS) Simulator User Guide" page.

This guide shows how easy it is to develop a graphics application using the MGS Simulator and port it to the desired target once the application is ready.

Required Hardware and Software

For the purpose of this training, the required hardware are as follows:

The required software is as follows:

Description of Example Application

In this training session, we will create a very simple button example with a couple of buttons that change the visibility of labels. The design has a single layer with very few assets.  Below, you will find a description of the GFX User Interface and its functionality.

Button example application

  1. Clicking the Press Me button will toggle the visibility of the "Hello World!" label.
  2. The Toggle button will alternately display "Button Toggle On!" and "Button Toggle Off!" labels.

Back to Top

Getting Started with the Application

In this section, we will learn how to use MPLAB X IDE to create the Button example. 

Back to Top

Create an MCC Project

 We start by creating an MCC project.

Click on the New Project icon.

New Project button

 

Back to Top


Select Application Project(s), click Next.

New Project window
 

Back to Top


In the Device textbox, type “sam9”, from the resulting list and choose SAM9X60D1G. Click Next.

Select Device pane

 

Back to Top


Select XC32 (v4.40) as the compiler. Click Next.

Select Compiler pane

 

Back to Top


In the last window, enter the Project Name and Project Location. Leave the Set as main project and Open MCC on Finish boxes checked. Click Finish.

New Project window

 

Back to Top


This will launch the MCC Content Manager Wizard. Click Select MPLAB Harmony.

MCC Content Manager Wizard

Back to Top


From the MCC Harmony Content Manager, choose the mandatory library for installation (bsp, csp, core, Devices, dev_packs, and gfx). If the required SW is already installed, the Content Manager will display a notification indicating that it is already in place. Click Finish.

MCC Content Manager Wizard

Back to Top


Build the Project Graph

Next, we will build the Project Graph by adding the necessary resources and configuring them. For this example, we build the project graph as explained in the following steps.

From the MCC Resource Management tab, select the following components from Device Resources by clicking on the add icon under Libraries > Harmony > Graphics > Simulator > MGS Web Simulator.

MCC Resource Management tab

This will ask you to add:

  • Harmony Core component. Say Yes.
  • FreeRTOS component. Say No.

Back to Top


Right-click on the yellow diamond against LE Display Driver of the MGS Web Simulator component and from the list of Consumers, choose Legato.

MGS Web Simulator component

Back to Top


Right-click on the yellow diamond against TMR of the MGS Web Simulator component and from the list of Consumers, choose TIME (sys_time).

MGS Web Simulator component

The MGS Simulator supports calls to Time System Service APIs. You may also print to a console using printf (line buffered). 

Back to Top


Select MGS Web Simulator from the project graph. From the Configuration Options for Display Type, choose WVGA

Configuration Options tab

 

Back to Top


The project graph now looks as shown:

project graph

Back to Top

Designing GUI with MGS Composer

With the MCC project created and the project graph ready, we will design the GUI using MGS Composer. For the purpose of this training, we will use a pre-made design.

Download the design ZIP file to the project at the location, GFX_Sim_Button\src\config\default.

Back to Top


 From the Project Graph > Plugins drop-down menu, launch Microchip Graphics Composer

Project Graph tabIf the project is not automatically opened in MGS Composer, click Load an existing project and choose the design file from Step 1. The composer displays the project design as shown in the accompanying image.

MGS Composer display

Take the time to observe the design in the MGS Composer including the images, strings, etc.

Back to Top


 Keeping the MGS Composer open, from the Resource Management [MCC] ​​​​​​tab, click Generate.

Resource Management tab

Back to Top


This will generate an MGSWS file in the GFX_Sim_Button\src\config\default folder. This file will be used by the MGS Simulator.

With this, we have finished designing the GUI, and using MCC, we have generated the required MPLAB Harmony code. We are now ready to develop the application code.

Back to Top

Application Code - Example

The Button example can be downloaded from GitHub.

Copy the app.c file to your project.

Take the time to observe the application code in app.c.

  • The event_Screen0_ButtonWidget_0_OnReleased event callback function toggles the visibility of Screen0_LabelWidget_0 label.
  • The event_Screen0_ButtonWidget_Toggle_OnPressed callback function sets the string of the Screen0_LabelWidget_1 label to string_toggleOn.
  • The event_Screen0_ButtonWidget_Toggle_OnReleased callback function sets the string of the Screen0_LabelWidget_1 label to string_toggleOff.

Back to Top

Building the Application Using MGS Simulator

Before using the MGS Simulator to build the demo application, make sure that you have installed and familiarized yourself with the Simulator. Also make sure that the MGS Simulator SDK is installed. To learn more, refer to the MGS Simulator guide. 

Back to Top

Using the MGS Simulator in Web Mode

To run the GFX demo application on the Simulator in Web mode, follow the tutorial steps:

Launch the project in MGS Simulator by double-clicking default.mgsws generated by MCC in the GFX_Sim_Button\src\config\default folder as explained in the "Designing GUI with MGS Harmony Composer" section.

Back to Top


Make sure that the Simulator is in web mode. To build the project, import the application file and click Build as shown in the accompanying graphic.

Import the application file and click build

Back to Top


On a successful build, you should see an output as shown in the accompanying image, including a link to the generated HTML file. Click on the link (highlighted) to launch the MGS Simulator output on your default web browser.

Output

The MGS Simulator output has been tested on Google Chrome™ browser and Microsoft Edge.

Back to Top


MGS Simulator Output

To interact with the MGS Simulator output:

  • Click on the Press Me button to see the visibility of the "Hello World!" label toggle.
  • Click on the Toggle button to see the accompanying text alternate between "Button Toggle On!" and "Button Toggle Off!".

Back to Top

Using the MGS Simulator in Native Mode

To run the GFX demo application on the Simulator in Native mode, follow the tutorial steps:

Launch the project in MGS Simulator by double clicking default.mgsws generated by MCC in the GFX_Sim_Button\src\config\default folder as explained in the "Designing GUI with MGS Harmony Composer" section.

Back to Top


Make sure that the Simulator is in Native mode. To build the project, import the application file and click Export as shown in the accompanying graphic.

Import the application file and click build

Back to Top


From the Export pop-up window, choose any location to export the cmake project. In the output console, you will immediately see a log message that the project export is complete.

output console

Ensure that Microsoft® Visual Studio Code (VS Code®) or a suitable IDE is installed with all the necessary extensions.   

Back to Top


Right-click on the folder to which the project was exported. You may have to hold down the shift key. Click on Open with Code.

Open with Code option

Back to Top


VS Code is launched with the project. In the pop-up window, click the Yes, I trust the authors button.

Do you trust the authors of the files in this folder? pop-up

Back to Top


Press F5 on your keyboard to build and run the demo in Debug mode. Alternately, click on the Run and Debug icon, then click the Debug button.

Run and Debug buttons

Back to Top


The demo application is launched in a separate window. Step through the code using the debug icons.

demo application window

Back to Top


Explore the application files using the project explorer and set breakpoints by pressing F9

project explorer

Back to Top


Porting to the Target

Now that the Button demo application is ready and tested using the simulator (in both Web and Native mode), we are ready to port it to the target, which is a straightforward process.

From the Resource Management [MCC] tab, select the following components from Device Resources by clicking on the add icon under Libraries > Harmony > BSP > SAM 9x60 Curiosity BSP.

Project Resources paneSelect Libraries > Harmony > Graphics > Templates > Legato Graphics w/ PDA TM5000 Display.

Device Resources pane

This will launch several pop-up windows asking you to confirm if other components can be added to the graph and if they can be interconnected. Say Yes to all pop-ups except FreeRTOS.

The project graph should now look as shown:

project graph

 

Back to Top


Disconnect LE Display Driver from MGS Web Simulator and connect it to LE LCDC Driver. Disconnect TMR from MGS Web Simulator and connect it to TC0.

Project Graph

Back to Top


Click MCC Generate.

Back to Top


From the Dashboard pane, click on the wrench icon Wrench Icon​​​​​

to launch the project properties. Select Building from Categories and select the Execute this link after build checkbox and in the textbox enter:
${MP_CC_DIR}/xc32-objcopy -O binary ${DISTDIR}/${PROJECTNAME}.${IMAGE_TYPE}.elf ${DISTDIR}/harmony.bin

Back to Top


Build the project by pressing F11 from your keyboard or clicking the Clean and Build Clean and Build Icon icon.

This builds the project successfully for the target. You will find harmony.bin generated in the GFX_Sim_Button\GFX_Sim_Button.X\dist\default\debug folder.

Back to Top


Copy the harmony.bin from GFX_Sim_Button\GFX_Sim_Button.X\dist\default\debug folder to a fat formatted SD card. Copy the boot.bin to the same SD card.

Back to Top


Connect the WVGA display to the SAM9X60 Curiosity board. Power the board by connecting a USB cable to J1. Insert the SD card to J3 and press the reset button.

You will see the Button demo on the display and the user experience should match what you saw with the MGS Simulator.

Back to Top