Microchip Graphics Suite (MGS) Simulator User Guide

Last modified by Microchip on 2024/06/21 11:29

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. 

Download the MGS Simulator EXE file for installation.

A typical graphics application development workflow uses the Microchip ecosystem as follows: 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. The application development workflow is represented in Figure 1.

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.

Graphical application development workflow

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 information on how applications can be ported to the desired target.

To use MGS Simulator, use gfx version of v3.15.0 from the Microchip GitHub repository.

MGS Simulator Installation

Download the MGS Simulator installer and unzip it to a location on your PC. Run the installer wizard. The MGS Simulator will be installed in C:\Users\<USER>\AppData\Local\Microchip Graphics Suite Simulator by default. 

Creating MGS Simulator Desktop shortcut

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.

Launching MGS Simulator

Figure 3: Launching MGS Simulator

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

Back to Top

MGS Simulator Layout

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

MGS Simulator Layout

Figure 4: MGS Simulator Layout

  1. 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.

  2. 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.

  3. About: Displays the About box for MGS Simulator. An example is shown in Figure 5.

    MGS Simulator About Box

    Figure 5: MGS Simulator About Box

  4. 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.

    MGS Simulator SDK Manager showing SDK is installed

    Figure 6: MGS Simulator SDK Manager showing SDK is installed

  5. 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. 

  6. 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.

    Project Details

    Figure 7: Project Details

  7. 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.

  8. Selection tool: You can choose only the required application files or all of them for compilation using the > or >> button. 

  9. Compilation files: Application files in your project chosen to be included for compilation are listed here.

  10. Clear Console: Clears the output console.

  11. Output Console: Prints useful information, build warnings, and errors. 

Back to Top

Using the MGS Simulator

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

A GUIX is designed using MGS Composer.

Back to Top

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).

Including MGS Simulator to project graph

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.

MGS Simulator Configuration

Figure 9: MGS Simulator Configuration

  • 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. 

mgsws file

Figure 10: .mgsws file

Back to Top

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

MGS Simulator with project open

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.

Back to Top

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

Open project with MGS Simulator

Figure 12: Open project with MGS Simulator

Back to Top

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.

SDK installed

Figure 13: SDK installed

Back to Top

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.

Back to Top

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.

Launch Simulator output html

Figure 14: Launch Simulator output html

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

Back to Top

MGS Simulator Output - Web Mode

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

Back to Top

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.

Using MGS Simulator in native mode

Figure 15: Using MGS Simulator in native mode

Back to Top

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

Exporting project to a folder

Figure 16: Exporting project to a folder

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

Project exported to the selected folder

Figure 17: Project exported to the selected folder

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

Back to Top

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:

VS Code installation options

Figure 18: VS Code installation options

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.

Open project in VS Code

Figure 19: Open project in VS Code

Back to Top

The project is launched with 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.

Trust the authors to open the project in VS Code

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.

Back to Top

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

Back to Top

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.

Debug session

Figure 21: Debug session

 

Back to Top

MGS Simulator Usage Examples

Graphical demo applications developed using MGS Simulator can be easily ported to the desired embedded target. A single MPLAB X IDE project can be maintained for both 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 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.

Back to Top

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 Display
  • For the target version, Plibs such as TC, GFX2D, I2C, LCDC, are used.

Back to Top

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.

Back to Top