Microchip Graphics Suite (MGS) Simulator User Guide

Last modified by Microchip on 2024/09/18 14:45

Introduction

The Microchip Graphics Suite (MGS) Simulator is a utility enabling users to test and debug graphical applications created using MGS Harmony Composer on a PC.

A typical graphics application development workflow uses the Microchip ecosystem as shown in Figure 1. The application developers easily design the GFX UI using MGS Harmony Composer and generate the required MPLAB® Harmony code using MPLAB Code Configurator (MCC). The application code required to control the GUI behavior is developed and debugged on the target.

To learn more about how to create an MPLAB Harmony graphics project, follow the tutorial in the link provided on the "Getting Started with Microchip Graphics Suite (MGS) Harmony" page.

Figure 1: Graphical application development workflow

The MGS Simulator helps ease and expedite the entire process by offering the following benefits:

Begin developing your application before hardware (target and debugger) procurement.
Flashing the code to the target could be time-consuming, therefore the tool helps save time.
Porting the simulator project to the actual target is trivial. Design once and use on multiple targets.
Sharing the simulator output with peers is easy. Because there is no reliance on specific hardware, peers can easily interact with the application and provide feedback.

This guide provides details on the MGS Simulator and how applications can be ported to the desired target.

To use the MGS Simulator, use GFX v3.15.0 or newer from the Microchip GitHub repository.

MGS Simulator Installation

Download the MGS Simulator installer (.exe) from GitHub.

Run the installer wizard by double-clicking on Microchip Graphics Suite Simulator_X.X_x64-setup.exe. The MGS Simulator will be installed in C:\Users\<USER>\AppData\Local\Microchip Graphics Suite Simulator by default.

Figure 2: Creating MGS Simulator Desktop shortcut

The MGS Simulator can now be launched using the desktop shortcut if selected during installation or from the C:\Users\<USER>\AppData\Local\Microchip Graphics Suite Simulator folder.

The layout of the MGS Simulator is described in the next section.

MGS Simulator Layout

Referencing Figure 4, take a few moments to familiarize yourself with the main sections of the MGS Simulator:

Open: The simulator project can be opened using the <config_name> .mgsws file generated by MCC.
The MGWS file generation using MCC is explained in detail later in this tutorial.
Refresh: Reopens the project. If the MGS Simulator settings are modified in the MCC project graph, as explained in the "Using the MGS Simulator" section, you may have to re-open the project for the changes to take effect. Instead the refresh button can be used.
Delete: Performs a "clean." The MGS simulator maintains a cache/snapshot of the graphics application in the C:\Users\<USER>\AppData\Local\Temp\mgsws-X folder. This may be required if one or more files in the Harmony project are deleted.
Target Selector: In Web mode, the simulator generates a .html file in the src/config/<config_name> folder, which can be opened in a web browser. The HTML file can be forwarded to a peer, who is then able to store it in any location on their computer and peruse the graphical application using a web browser.
In Native mode, the simulator generates a cmake project which can then be opened using an IDE such as Microsoft® Visual Studio Code or Eclipse for debugging on their computer.
About: Displays the About box for the MGS Simulator. An example is shown in Figure 5.
Figure 5: MGS Simulator About Box
SDK Downloader: Launches the SDK Manager. The MGS Simulator SDK is installed in the C:\Users\<USER>\AppData\Roaming\com.microchip.mgsws folder. If the SDK is not already installed, the first time a Simulator project is built, the SDK manager is automatically launched and the user is prompted to download and install the SDK. Figure 6 shows the SDK is installed.
Figure 6: MGS Simulator SDK Manager showing SDK is installed
Build/Export: In Web mode, the Build button is displayed. The user is able to build the simulator project to generate an HTML file in the src/config/<config_name> folder.
In Native mode, the Export button is displayed. The user is able to choose a location to create the cmake project.
Project Details: Lists project details such as screen size, color mode, layer count, and whether Canvas and System Time are being used. Figure 7 shows an example.
Figure 7: Project Details
Project application files: Lists all the application files (app.c) in the MPLAB X IDE project. When the simulator project is opened, all the application files are listed here.
Selection tool: You can choose only the required application files or all of them for compilation using the > or >> button.
Compilation files: Application files in your project chosen to be included for compilation are listed here.
Clear Console: Clears the output console.
Output Console: Prints useful information, build warnings, and errors.

Using the MGS Simulator

To use the MGS Simulator, let us recall the workflow shown in Figure 1:

A GUIX is designed using MGS Composer.

An MPLAB X IDE project is created and using MCC, the MGC Composer design is imported. From the MCC Resource Management tab, Device Resources > Libraries > Harmony > Graphics > Simulator, click on the + button next to MGS Web Simulator to include the simulator and other required resources for your project (as shown in Figure 8).

Figure 8: Including MGS Simulator to project graph

The "MGS Web Simulator" exposes LE Display Driver interface to use with either Legato or Canvas.
If Canvas is used in the project graph, in the Object Configuration, the canvas object frame buffer allocation type may be set to dynamic.
printf statements may be used in the application code with \n, which can be viewed in the browser or IDE console.
It also provides a Simulated Timer for Time System Service.

The Configuration Options for the MGS Simulator can be modified as shown in Figure 9.

Selecting the Responsive feature is especially useful to show the HTML output on mobile devices or displays with varying sizes.
If you plan to embed the HTML output on an iframe, we recommend deselecting the Bezel and Responsive options to reduce the HTML size.

The Generate button generates a .mgsws file and is generated in the src\config\<config_name> folder.

Double-clicking on the .mgsws file will open the project in the MGS Simulator.

Figure 11: MGS Simulator with project open

In the next section, we will learn how to build the MGS Simulator project in Web and Native mode.

Using the MGS Simulator in Web Mode

In Web mode, the MGS Simulator builds the demo application as an HTML file. An example is shown in the "MGS Simulator Output" section.

To build the GFX demo application using the MGS Simulator in Web mode, follow the tutorial steps:

Open the project in the MGS Simulator by double-clicking on the .mgsws file or click Open and choose the .mgsws file in the src\config\<config_name> folder.

Figure 12: Open project with MGS Simulator

Before building a project with the simulator for the first time, an SDK is required. To install the SDK, click on the SDK Downloader, and from the SDK Manager, select the SDK and click Download.

InstallSDK

Once the SDK is installed it will be enclosed in a green box as shown in Figure 13. Close the SDK Manager.

Import the application file(s) to be included for compilation and click Build as shown in the accompanying graphic.

Import the application file and click build

If you have multiple application files, you can import all of them using the >> button or individual files using the > button. You can also remove files chosen for compilation using the < or << buttons.

Application or user-created source files must be in the firmware/src/ directory for the MGS Simulator to import. Application source files that contain the screen and widget callback definitions must be imported into the MGS Simulator for the simulator build to succeed.

Peripheral library or HW-specific calls in the application source files will not build in the MGS Simulator. Use the MGS_SIM macro to exclude these calls for a simulator build (e.g., #ifndef MGS_SIM).

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

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

MGS Simulator Output - Web Mode

The following is an example of MGS Simulator output in Web mode.

Using the MGS Simulator in Native Mode

In Native mode, the MGS Simulator builds a cmake project. A suitable IDE such as Microsoft Visual Studio Code can be used to debug the project further on the PC.

To build the GFX demo application using the MGS Simulator in Native mode, follow the tutorial steps:

Switch to Native mode and click the Export button.

Figure 15: Using MGS Simulator in native mode

Choose any folder where you want to save the cmake project and click Select Folder.

Figure 16: Exporting project to a folder

The project is exported to the selected folder as indicated by the console log.

Figure 17: Project exported to the selected folder

In the next section, we will see how to debug the project in VS Code®.

Debugging the Project in VS Code

If you do not have Visual Studio Code installed, please install it. During Installation, ensure that all the installation options shown in Figure 18 are selected:

To debug the demo project natively on your PC, follow these instructions:

Right-click on the folder to which the project was exported in the "Using the MGS Simulator in Native Mode" section. You may have to hold down the shift key. Click on Open with Code.

The project is launched and the user is prompted to choose if the author of the files in the folder can be trusted. Choose Yes as shown in Figure 20.

Figure 20: Trust the authors to open the project in VS Code

If you are prompted to install any extension(s) when the project is launched in VS Code the first time, select Install.

C/C++ Extension Pack (For GDB deubg)

C/C++ Extension pack

CodeLLDB (For LLDB debug)

CodeLLDB Extension

To build and Run/Debug, press F5 or click the Run and Debug icon as shown in the accompanying graphic.

Import the application file and click build

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

Press F9 to set breakpoints.

MGS Simulator Usage Examples

Graphical demo applications developed using the MGS Simulator can be easily ported to the desired embedded target. A single MPLAB X IDE project can be maintained for both the target and simulator.

The simulator is capable of handling applications of all levels of complexity without any restrictions, such as:

More than one layer in the Composer design
With Canvas enabled or disabled, etc.

The examples below show how to develop graphical applications using the MGS Simulator and subsequently port it to a target. We can see that the process flow is exactly the same no matter the complexity of the application.

Button Example

A simple button example is presented on the "Microchip Graphics Suite (MGS) Simulator Button Example" page. Some salient features of this example are:

The Composer has a simple single-layer design
Canvas is not used
The target used - SAM9X60 Curiosity Development Board and 5-inch maXTouch® Technology Display
For the target version, Plibs such as TC, GFX2D, I2C, LCDC, are used

EV Charger Example

A more complex example is presented on the "Microchip Graphics Suite (MGS) Simulator EV Charger Example" page. Some salient features of this example are:

The Composer design is very complex and has three layers
Canvas is used
The target used - SAM9X60 Curiosity Development Board and 5-inch maXTouch® Technology Display
For the target version, Plibs such as TC, RTC, GFX2D, I2C, LCDC, are used