ProgramModelUart GuiComposer

GUI Composer and UART support with standard monitor.

Introduction

This section explains how to use UART based data transmission between host PC and target SW/HW system. The data can then be used to populate displays in GUI Composer or to send commands to the target. In general the concept of creating a GUI Composer application is the same as for a JTAG based solution. i.e. widgets are dragged and dropped, then global variables are entered into bindings section for each widget. Please see this tutorial if you are not familiar with GUI Composer. The main difference is that serial based communication requires UART monitor. The solution is based on a standardized host side implementation and a monitor that needs to be integrated into target application.

Example Solution (Host GUI Composer app and target application)

The objective of this section is to import necessary projects and get to the point where example GUI Composer application is sending/receiving data over UART. The example GUI Composer application has only a few widgets for purpose of this demo. This example application requires Code Composer Studio v5.5 or higher and an MSP430 or C28x device(Sample apps have been tested with MSP430G2553 launchpad and 28069 control stick). The target program has a single variable "ErrorCount" that is continuously incremented. Sample GUI Composer application demonstrates couple of widgets that display this value (i.e. read) and a single widget that writes to this variable. 

MSP430 Software Requirements

• CCS Project for your device
• GUI Composer Application

MSP430 Hardware Requirements

If using the MSp430G2553 Launchpad, make sure the jumpers on J3 are set to HW UART. Refer to Step 5 in the Launchpad Quick Start Guide

C28xx Software Requirements

• TI Control Suite software package
• CCS project for your device
• GUI Composer Application

Steps:

• Download software requirements for device that you are working with.
• Unzip CCS Project into a directory and Import CCS project into CCS (Project->Import Existing CCS project menu), please ensure the "Copy projects into workspace" option is disabled. Hit build to verify that project builds. Please refer to C28_uart_monitor project description if build fails. 
• Import GUI Composer Project. We will need to open GUI Composer (View->GUI Composer menu) and then select Import Project button and navigate to uart_demo_app.zip file, specify the .zip file instead of unzipped directory.  You may get a pop up dialog asking you to upgrade project files, click Ok.
  • You should now see a simple GUI Composer application that looks like below. If you do not, then please expand project view in GUI Composer Designer and double click on app.html file.

• We now need to adjust target configuration file for your particular system.
  • Choose one of the following that matches your device
    • MSP430
      • Select MSP_uart_monitor project in CCS Project Explorer, expand it and double click on .ccxml file. CCS Setup Editor will open which is configured for MSP FET and G2553 launchpad.
    • C28xx
      • Select C28_uart_monitor project in CCS Project Explorer, expand it and then expand "TargetConfigurations" and double click on .ccxml file. CCS Setup Editor will open, which is configured for USB TI XDS100 v2 emulator and TMDS320C28069 device. You may need to adjust emulator selection if you have a different emulator.
  • We now need to add UART driver support by clicking on "Add" button under “Alternate Communication” section. You will then need to adjust COM port number that matches your system. Click on "ComPort" entry and adjust settings in COM Port: edit box. Click Save. 
• Start a debug session with our target project
  • MSP430
    • Click on MSP_uart_monitor project and hit Debug toolbar button.
  • C28x
    • Click on C28_uart_monitor project and hit Debug toolbar button.
• There might be a pop up dialog listing two options for loading a program. Please enable only the option that is NOT called ComPort. We will load symbols that UART connection(i.e. ComPort) will use later.
• Once a debug session starts and program is halted at main, hit run and then select ComPort node in CCS Debug View and choose Run->Load Symbols menu, click on Browse Project and choose .out file from target application project that we just debugged.
• You should now be able to enter “ErrorCount” variable in Expressions view, click on continuous refresh and see that the value is continuously updated.

• Now activate GUI Composer view by clicking on its tab, then click on “Preview” button in GUI Composer which will start preview of the example application, the widget is bound to the same variable that we added to expression view, thus expression view and the widget should be showing the same data. If you get red error indicators beside widgets, then it means that you have no loaded symbols on uart/ComPort connection.
• Next step is integrate uart monitor into your own application and create a GUI Composer application that controls your target systems parameters.
  

Example Solution Details

GUI Composer Application (uart_demo_app.zip)

Gui Composer sample application is very simple and it only interacts with a single global variable “ErrorCount” that is defined in main.c file. Error Count is a variable that is continuously incremented when a timer interrupt triggers. GUI Composer sample application displays this variable in a text box and graphs it using a scalar graph (it is a graph that accumulates a scalar variable’s data into buffer on every refresh cycle and then graphs resulting buffer). Last control in the sample application is a button that writes a fixed value to the target, in this case it writes value of 0, thus “resetting” the Error Count.

Target Project 

MSP_uart_monitor project description

• Target project contains 3 source files that are of interest which comprise target application. main.c is the file that contains main function that initializes the device and peripherals for this example. This is also where the “work” of the application occurs. The work is limited to incrementing ErrorCount variable based on a timer interrupt. uart.c provides basic abstraction for UART peripheral. Lastly, Serial_Cmd_Monitor.c is the file that implements the Monitor that services memory read/write requests that GUI Composer initiates. Symbol resolution occurs on the host and thus monitor deals strictly with address/length type of read/write requests. You may take sample monitor implementation and integrate it with your application. Alternatively, you may re-implement the monitor that integrates better with your target application. The protocol to exchange data is described in “Monitor protocol documentation” section.

C28_uart_monitor project description

• Target project contains 3 source files that are of interest which comprise target application. main.c is the file that contains main function that initializes the device and peripherals for this example. This is also where the “work” of the application occurs. The work is limited to incrementing ErrorCount variable based on a timer interrupt. UART_Comm.c  provides basic abstraction for UART peripheral. Lastly, Serial_Cmd_Monitor.c is the file that implements the Monitor that services memory read/write requests that GUI Composer initiates. Symbol resolution occurs on the host and thus monitor deals strictly with address/length type of read/write requests. You may take sample monitor implementation and integrate it with your application. Alternatively, you may re-implement the monitor that integrates better with your target application. The protocol to exchange data is described in “Monitor protocol documentation” section.
• NOTE!: Target application requires Control Suite to be installed. The sample project has macros configured to find Control Suite at C:\ti\ControlSuite. If you have installed ControlSuite in a different location, then you will need to adjust C28_uart_monitor project to match your system. You would see yellow warning icons on some source files when you expand project in Project Explorer. Select Project and click on Properties, in the dialog Expand “Resource : Linked Resources”. You should now see Path Variables on the right hand side of the dialog. Select “INSTALLROOT_F2806x_V1361” macro, then click on "Edit" button, then on Folder and navigate to ControlSuiteInstallationLocation\device_support\f2806x\vnnn, where nnn matches version from your ControlSuite software. Click Ok to close the dialog, in a few seconds warning icons should be replaced by linked file indicators (small arrow). You should be able to build your project now. 
  

Monitor Component Specification (Serial_Cmd_Monitor.c and Serial_Cmd_Monitor.h)

There are two “public” functions for the monitor component exposed through the .h file:
void ClearBufferRelatedParam();
- initializes the buffer pointers to 0

void receivedDataCommand(unsigned char d);
- feed directly by the uart input character by character. When a full command is received, the command will be handled accordingly

The other “private” helper functions for the monitor component is only defined in the .c file and can be classified as follow: Device specific functions:

  GetTargetEndianness()
Write8bitByteToCOM()
GetSizeOfMAUIn8bitByte()

Data buffer functions:

  WriteToCmdBuffer()
ResetInCmdBuffer()
WriteByteToInCmdBuffer()

Parsing command:

  GetTransferSizeInMAU()
VerifyInputCmdHeaders()
GetInputCmdType()
GetRWFlag()
GetInCmdAddress()
GetWriteCmdDataMAU()

Construct command:

  WriteMAUToCOM()
MemAccessCmd()
ProcessCommand()

Monitor Protocol Documentation

The host talks with the device through a simple command protocol. Only two commands are supported, read and write.

 (R)ead operation

• Host sends 5 byte message header
• Device replies with 1 byte message header + data read from the device memory

(W)rite operation

• Host sends 5 byte message header + data to be written
• Device replies with 1 byte message header

1 byte header

   MSB: 1 bit – reserved; set to 1
            2nd bit – R=1 or W=0
   LSB 6 bits length – up to 63 MAU(minimum addressable unit)

5 Byte header

Byte 1: 

   MSB: 1 bit – reserved; set to 1

            2nd bit – R=1 or W=0

   LSB   6 bits length – up to 63 MAU(minimum addressable unit)

Bytes 2-5

   32-bit address – in big endian

Data for read/write commands is always in device endiannes. 

1 byte header and 5 byte header share the same structure in first byte. 

Target Configuration : How to add UART support

The easiest way to enable support for UART for use with GUI Composer is to start from an existing JTAG target configuration file. (i.e. .ccxml). You can simply open .ccxml file and on the basic page you should be able to click on “Add” button under “Alternate Communication” section. You will then be able to specify Com port number that matches appropriate com port on your system by selecting it in List box and adjusting its property on the right hand side.
Starting a debug session with this configuration file will show two nodes in Debug View. One that is JTAG connection and second that is the UART connection. In Code Composer Studio, GUI Composer Designer will use the connection that is currently selected in Debug View for obtain data.

Exporting Application for use with GUI Composer Runtime

It may be desirable to export your application and provide it to colleagues or customers in a standalone form. In this case end user clicks on an executable application launcher, which starts the runtime to host your application. The end user experience is similar to starting a regular desktop application. Please see this topic on export. The main difference is that export dialog needs to have UART connection selected during export.

It is also important to ensure that your device has your target program pre-loaded and device is in a running state as GUI Composer Runtime will not load program or put it in a running state. It will simply open a COM port specified and attempt a data exchange. 

Picture below is an example and will need to be adjusted for your device. 

Connection: Specifies UART driver on the host. For UART based communication always choose this connection setting. 

Connection Filter: Regular expression allowing you to narrow down the list of connections that end user will see in deployed application. In this case we want to limit Connections to UART.

COM Port Filter: On windows machines it is possible to obtain a short description of a device attached to a COM Port from device manager. A regular expression string may be entered to automatically search through available COM Port devices and if match occurs, then that COM Port will be used by GUI Composer Runtime. If there are more than one match, then the first one will be used.    

Device: Specific device that this application is targeting. 

Device Filter: Similarly, as for connection it is possible to switch to a different device in an application. The filter allows to narrow down this list, thus making it easier for end user to get a list of applicable devices. A regular expression is required. 

Program File: This should be program file (.out) that this application interacts with. In UART applications program file is used to obtain symbols and their addresses.