Microchip Graphics Suite (MGS) Web Simulator

Last modified by Microchip on 2024/03/29 13:36
Contents

Introduction

The Microchip Graphics Suite (MGS) Harmony Composer helps application developers easily design the GFX UI and along with MPLAB® Code Configurator (MCC), generates the required MPLAB Harmony code. Subsequently, the application code required to control the 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.

 Microchip offers two useful tools to help ease and expedite the entire process:

  1. MGS Harmony Web Simulator (Beta Trial)
  2. MGS Harmony Desktop Emulator (Available in April 2024)

The benefits of utilizing these tools for creating your graphical application, rather than coding for the intended platform directly, include the following:

  • 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/Emulator 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 shows how to develop a graphical application using the MGS Harmony Web Simulator and easily port it to the desired target.

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

For the purpose of this training, we will develop an EV Charger example application whose GFX UI and behavior are described below.
EV Charger example application

  1. From the first screen displaying the "Please plug your car" message, pressing the red power button launches the charging screen with the charge cable animation.
  2. Pressing the + and - buttons beside the battery increases/decreases the battery percentage and changes the string for output power, charge time, etc. 
  3. If 100% battery charge is reached, "Battery Fully Charged" is displayed. Pressing the green power button reverts to the first screen.
  4. From Screen 2, on a 10-second idle time, the "Charging..." screen is displayed. Pressing anywhere on the screen reverts to the charging (second) screen.

Back to Top

Getting Started with the Application

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

Create an MCC Project

We start by creating an MCC project.

Click on the New Project icon.
New Project icon
Select 32-bit MCC Harmony Project and click Next.
Select 32-bit MCC Harmony Project
In the next window, keep the default setting for MPLAB Harmony Repository and Framework Path. Click Next.
keep the default setting for "Harmony Repository" and "Framework Path
Enter the Location, Folder, and Name for the project. Click Next.
​ Enter Location, Folder, and Name for the project.
Enter the project configuration name and select SAM for the Device Family and SAM9X60D1G for the Target Device. Click Finish.
Configuration settings
This will launch the MCC Content Manager Wizard. Click Select MPLAB Harmony.
MCC Content Manager wizard
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 finish screen

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, Device Resources > Libraries > Harmony > Simulator, Click on the + button next to MGS Web Simulator. This will prompt you to include other resources in your project. Click Yes for the Harmony Core and Input System Service. Click No for the FreeRTOS and PIT.
Build the Project Graph
Select MGS Web Simulator in the Project Graph.  From the Configuration Options, for Graphics Display Subsystem choose WVGA.
Configuration options

Optionally, for Webpage Options, unselect Bezel and Responsive. 

  • Selecting "Bezel" will create a frame around the display on the MGS Simulator output shown on the browser.
  • Selecting "Responsive" will scale the size of the display on the web browser based on the browser window size. This 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, it is recommended to uncheck these two options to reduce the HTML size.
On the project graph with MGS Web Simulator selected, right-click on the yellow diamond for TMR and choose sys_time.
Simulator component in MCC graph
Similarly, right-click on the yellow diamond for LE Display Driver and choose gfx_canvas.

Select Graphics Canvas from the project graph. Right-click on the yellow diamond for LE Display Driver and choose gfx_legato. From the Configuration Options, set the number of Canvas Objects to 3 and their width, height, color mode, and frame buffer allocation.
Graphics Canvas settings

For the MGS Harmony Web Simulator, the Frame Buffer Allocation should be set to Dynamic.

The final Project Graph should look as shown in the accompanying image.

final Project Graph

Designing GUI with MGS Harmony Composer

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

Download the design ZIP file to the project at the following location: EVCharger\firmware\src\config\lcdc_rgba888_mxt_9x60_wvga.

From the Project Graph Plugins drop-down menu, launch Microchip Graphics Composer. 
launch MGS Harmony Composer

This will automatically launch the project design as shown in the accompanying image.

project design is automatically launched

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

Keeping the MGS Harmony Composer open, from the MCC Resource Management tab, click Generate.
Click generate

This will generate an MGSWS file in the EVCharger\firmware\src\config\lcdc_rgba888_mxt_9x60_wvga folder. This file will be used by the 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.

Application Code - Example

The EV Charger example application can be downloaded from GitHub.

Copy the app.c and app.h file to your project.

Take the time to observe the application code in app.c and app.h:

  • Three canvas layers are set up with size and position. The third canvas is used for the charge cable animation.
  • LeFixedString variables to display the meter readings, etc. are created and pointers to cable images are initialized for animation. 14 pictures of cables are cycled through using gfxcSetPixelBuffer to animate the charge cable.
  • Three timers are set up for cable animation, to track idle time for Screen 2 and to animate the microchip icon and the battery on Screen 3.
  • Touch input listener is added to track user input to return from Screen 3 to Screen 2.
  • Button event handlers are added for the power buttons, and the +/- buttons. 
  • Logic is added to track which screen is displayed and updated accordingly using gfxcShowCanvas/gfxcHideCanvas.

Back to Top

MGS Harmony Web Simulator - Installation and Usage

In this section, we will learn how to install and run the simulator. The output of the Graphics application is viewed on a web browser.

MGS Harmony Web Simulator installation

Download the MGS Harmony Web Simulator installer and unzip it to a location on your PC. Run the installer wizard. The Simulator will be installed in C:\Users\<USER>\AppData\Local by default. You may choose to create a desktop shortcut which is done by default.

MGS Web Simulator Setup

Using the MGS Harmony Web Simulator

To run the GFX demo application on the simulator, follow the tutorial steps:

Launch the MGS Harmony Web Simulator installed in the C:\Users\<USER>\AppData\Local folder or use the desktop shortcut (if selected during installation).

Launch the MGS Simulator

Click Open and choose the lcdc_rgba888_mxt_9x60_wvga.mgsws file in the EVCharger\firmware\src\config\lcdc_rgba888_mxt_9x60_wvga folder generated by MCC as explained in the "Designing GUI with MGS MPLAB Harmony Composer" section.

Click "Open"

Choose the lcdc_rgba888_mxt_9x60_wvga.mgsws file
 

An SDK is required to use the Simulator which is installed on the first build.

Click on the Build button. 

Click on the Build button

The simulator will launch the SDK Manager and prompt you to download the required SDK.

mgsws_sdk_win_x64 update in SDK Manager - 3.1

Click on the SDK to select it, and click Download.

Download the required SDK
The SDK will be downloaded and extracted to the C:\Users\,USER>\AppData\Roaming\com.microchip.mgsws folder. 

Close the SDK Manager.
close SDKManager

With the SDK installed, we are ready to build the project. Import the application file and click Build as shown in the accompanying graphic.

Import the application file and click build

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 Harmony Web Simulator output on your default web browser.

Click on the link (highlighted) to launch the MGS Simulator output

The MGS Harmony Web Simulator output has been tested on Google Chrome and Microsoft Edge.

MGS Harmony Web Simulator Output

To interact with the MGS Harmony Web Simulator output:

  • Click on the red and green power button.
  • Click on the + and - buttons next to the battery and observe the changes.
  • From the charging screen (with the animated power cable) on a 10-second idle time, the Charging screen is launched. Observe the Microchip logo animation.
  • Click anywhere on the screen to revert to the charging screen.

Back to Top

Porting to the Target

Porting the MGS Harmony Web Simulator project to the target is quite trivial. A simple method is described in the following steps.

Start with the Legato™ Quickstart example project for the SAM9X60 Curiosity.  If you do not have the gfx_apps_sam_9x60 repository available on your PC, you can download it from GitHub.
Open the gfx_apps_sam_9x60\apps\legato_quickstart\firmware\legato_qs_9x60_cu_tm5000.X project using the MPLAB X IDE. 

Launch MCC and make changes to the project graph as described in the following instructions.

Include Graphics Canvas to the project graph.

Include Graphics Canvas to the project graph

Select LE LCDC Driver from the project graph and then from Configuration Options, select Canvas Mode.

Select configurations

Select Graphics Canvas from the project graph and from the Configuration Options, set the Canvas Objects to 3, and set their values as shown in the accompanying image.

Graphics canvas configurations

Copy the design files from the MGS Simulator project to the Legato Quickstart project at the following location: legato_quickstart\firmware\src\config\lcdc_rgba8888_mxt_9x60_cu_wvga

and rename it to "lcdc_rgba8888_mxt_9x60_cu_wvga_design". 

Do not forget to delete the existing design file or rename it to something else.

Launch MGS Harmony Composer and ensure that you see the same design as you did in the "Designing GUI with MGS MPLAB Harmony Composer" section.
Replace the app.c and app.h files (in the legato_quickstart\firmware\src folder) of the Legato Quickstart project with the ones from MGS Harmony Web Simulator project.

Connect the WVGA display and the JTAG debugger to the SAM9X60 Curiosity board. Power the board, download and debug the project on the target.

You should see the EV Charger demo on the display and the user experience should match what you saw with the MGS Harmony Web Simulator.

Back to Top