4.2. Target programming

GUI Composer offers a number of different options to obtain data from your target device or to send data to your device based on user actions.

v3 Component library projects only If you select Application V3 project template, then you will need close the wizard on first page by clicking OK. Target Communication and device programming is configured by dragging and dropping non-visual components. Please refer to Tutorials section for more information.

Clicking Next from the New Project Wizard will move you to next page in the wizard where you can choose to program your device. This is an optional page that may be used to update the program that is running on the target system.

Specifying device and program file is required for XDS target communication options.

Click on the Add button, which will add a new entry with these options:

  • Device: You will need to specify device. You may enter partial device name to limit the set of options.

  • Connection:This field in most cases is auto populated based on selected device in previous step.

  • Executable: Click on Upload to select a program file from your local file system. This field shows the program (i.e. .out) file that is used to program the MCU or it is used to obtain symbolic information for XDS target communication options.

  • Auto Programming: This is an optional step in all scenarios. If option is enabled then before starting the application, GUI Composer will program the device.

4.2.1. Target Communication

Clicking Next will move you to next page in the wizard where you can choose your Target Communication method. Click on the image0 button in top left corner to add a target communication option.

Each target communication option has a slightly different set of options. However, generally after adding a particular transport you would need to add a model representation for your data.

4.2.1.1. Interacting with a Target Device (Applicable to v2 projects only)

There are a number of different Target Communication options that you can use for data exchange with a target device. The choice for your specific GUI Composer application will depend on your target device, your application program and how the device is connected. During new project creation you will need to choose which target communication method your target firmware should use. You may also change or adjust target communication method later through project properties.

GUI Composer now supports multiple data connections in a single application. You may combine USB-UART to stream data for visualization and add XDS communication option to write user changes to control the operation of target firmware.

(Supported on some devices only)

In most cases you will need to choose a physical connection like a transport and a data encoding / protocol that is used to transfer data. For example,the USB-UART option uses a USB cable to connect your device, where data is sent through UART. One of the protocols for encoding data is JSON. Some choices may have a fixed protocol e.g. XDS uses JTAG protocol.

In general the Target communication selections are as follows: - Click on + button in top left corner and select physical transport (e.g. Network based transport) - Add a data model by clicking on add-verbose button. Model specific options will be automatically presented. Exact listing of options depends on selected Target Communication option.

4.2.1.2. Network (Applicable to v2 projects only)

  • Not supported in GC Component library v3 projects.

In this case we are using Network based communication channel to talk to the device.

IBM IOT (Applicable to v2 projects only) - Not supported in GC Component library v3 projects.

The target code is linked with an ‘MQTT’ library that handles communication with IBM IoT MQTT Broker, enabling the project to send and receive JSON formatted strings via the Internet.

GUI Composer uses bindings to the ti-model-iot-ibm component to allow widgets to be automatically updated to reflect the value of received JSON-formatted property strings when those values change, and to transmit property values to the target via JSON-formatted strings when a widget is configured by the user.

Please refer to the IoT Tutorial for details on how to do this.

Use IBM IoT if:

  • Your target can communicate with the Internet

  • You are using IBM IoT broker either Quickstart or authenticated to communicate with your target

  • You would like your application to communicate with your device without a direct physical connection

MQTT (Applicable to v2 projects only) - Not supported in GC Component library v3 projects.

The target code is linked with an ‘MQTT’ library that handles communication with an MQTT Broker, enabling the project to send and receive JSON formatted strings via the Internet.

GUI Composer uses bindings to the ti-model-iot-mqtt component to allow widgets to be automatically updated to reflect the value of received JSON-formatted property strings when those values change, and to transmit property values to the target via JSON-formatted strings when a widget is configured by the user.

Please refer to the IoT Tutorial for details on how to do this.

Use MQTT (IoT) if:

  • Your target can communicate with the Internet

  • You have configured an MQTT broker to communicate with your target

  • You would like your application to communicate with your device without a direct physical connection

HTTP (Applicable to v2 projects only) - Not supported in GC Component library v3 projects.

The target code is built with a webserver which GUI Composer application uses to obtain data. There are two schemes that are supported, urlecoded and JSON.

Once you click on Add and add HTTP model, you will need to enter the webserver address and optionally provide credentials. Once webserver connection information is specified you will need add variables that represent your data. You will need to click on Add and fill in a variable name, then a path that webserver needs to respond to and then whether the data will be urleconded or JSON format. JSON format allows to return multiple data pieces in an object.

Use HTTP if:

  • Your target can communicate with the Internet

  • You have configured a webserver to communicate with your target

  • You would like your application to communicate with your device without a direct physical connection between PC and target system.

4.2.1.3. USB - UART

  • All USB-UART Transports target communication options are supported in Components v3 library, please refer to Tutorials section for more information as configuration steps are different.

The target device is physically connected with a USB cable and data is sent using UART peripheral. You may optionally specify device ID which will help with automatically selecting the right COM port.

Once you click on Add, there are two options supported, Monitor and Streaming.

Monitor model is used to simulate XDS type communication with assistance of target monitor. In this case data is encoded through a custom monitor that needs to be integrated with your target program (firmware). GUI Composer has a host side implementation that can obtain the information, but it requires a target side implementation that uses the same protocol. Using monitor based protocol

This is an example of pull based protocol as GUI Composer infrastructure will periodically pull data from target device.

Please see USB - UART with monitor Tutorial more information.

Streaming model is used consume data that target is continuously streaming to the host PC. There are two schemes supported, JSON and Custom:

  • JSON: In this case data is sent using JSON formatted strings.Please see JSON Strings topic for more information on JSON. Please see this the Serial Tutorial for an example of USB - UART over JSON project that received JSON encoded data from the device. This is an example of push based protocol as target application pushes data to client (i.e. host PC)

Please see Serial Communication Tutorial more information. You may also see examples of JSON communication options in MSP430Ware package MSP430Ware GUI Composer examples There are examples for MSP430 based LaunchPads that include example firmware and GUI projects.

  • MessagePack: In this case data is sent using MessagePack protocol, which is very similar to JSON but a more efficient binary protocol. MessagePack offers many libraries in a number of different languages. Please see [MessagePack.org] (https://msgpack.org/index.html) for more information.

  • Custom: In this case the target application can send custom data that is optimized for your application. This option provides the greatest efficiency in sending the data as only the specified data is sent. The disadvantage of this method is the hand-written custom Javascript functions that parse the data and bind them to widgets. This method is an example of push based protocol as target application pushes data to client (i.e. host PC) Using custom based protocol

4.2.1.4. USB - XDS

  • USB-XDS is supported in Components v3 library, please refer to Tutorials section for more information as steps to add this target communication are different for v3 projects.

The GUI Composer application uses a debug probe for physical connection (in most cases this is also over USB cable) for data exchange.A program file (i.e. your firmware) is used to obtain symbolic information to bind to widgets. - Widget bindings use global variables that exist in your program.

GUI Composer’s infrastructure will convert symbolic data to memory addresses that are then read or written from/to.

  • This option is often the simplest to get started with as it does not require any special target program changes or any special handling on the client (host) side. However, it does require device and debug probe to have support for non-intrusive memory access. This option is available on Cortex based MCU’s and C2000 devices.

Use XDS if:

  • You are converting a project from GUI Composer 1 to GUI Composer 2 or you have a CCStudio project that you wish to add a user interface to without writing much target-side code to provide the interface API

  • You would like the freedom to bind to any global variable on your target without having to change your target-side code

  • Your GUI Composer application will pull data from the device on a fixed timer interval.

4.2.2. Communicating using JSON-formatted strings

JSON, IBM IoT and MQTT target communications options use JSON-formatted strings for messages. For more information on JSON format please visit JSON.org.

  • All fields are case-sensitive, and will not work properly if there are any errors in spelling, uppercase vs. lowercase letters, punctuation, etc.

  • Use “straight double quotes”, not curled “quotes”

  • \n (0x0A) is used as a delimiter between objects

    • Do not use \n as line ending within the JSON string

Example: the following works:

{"temp":72.51,"LEDs":{"Red":1,"Green":0}}\n

Example: the following DOES NOT work:

{\n
 "temp":72.51,\n
 "LEDs":{\n
        "Red":1,\n
        "Green":0\n
      }\n
 }\n

Here’s an example of target code (using the Energia Serial library) to send a JSON response to your GUI Application:

int greenLedState = HIGH;
int redLedState = HIGH;
...

Serial.print("{\"LEDs\":{\"Red\":");
Serial.print(redLedState, DEC);
Serial.print(",\"Green\":");
Serial.print(greenLedState, DEC);
Serial.print("}}\n");

When binding to a property like the Green property in the above example, dot notation is used, so to bind to the value of the Green LED, use LEDs.Green

When sending a value to the target, the JSON object will be dynamically created based on the binding value you enter.

Example: if you enter LEDs.Blue as the binding target for a checkbox’s checked property, even though there is no entry on the target for this JSON object, the target will be sent the following string:

{"LEDs":{"Blue":true}}\n

Where true would be replaced by the value of the checkbox’s checked property.

  • It is important to note that the type of the widget’s property (e.g. boolean) determines what will be sent to the target (e.g. true), and the target is responsible for handling this.

4.2.3. Configuration Dialogs for USB-UART : JSON, IBM IoT and MQTT

‘Teach’ GUI Composer the JSON strings your target program is sending to enable auto-completion

  • You can make it MUCH easier to bind the JSON property/value strings sent by the target to your GUI applications widgets by using one of the advanced features of the Target Communications configuration dialogs.

  • The Configuration Dialog is displayed when you are creating a New Project and have selected either “USB-UART : JSON”, “IBM IoT” or “MQTT” as the protocol in Target Communications dialog. You may also open it at any time by clicking on Project : Properties and clicking Next in the pop up dialog.

  • When the Target Communication wizard page is active, click on a particular target communication method in the left side of the tree to choose your target communication method. This would show settings for that particular data exchange method. You would then click on Connect and then click on Console buttons. GUI Composer will attempt a connection to your device or broker and show the data that it is receiving in the console. This accomplishes two objectives.

    • It verifies that connection can be established successfully

    • GUI Composer parses received JSON strings and creates a table of names that can be used when specifying widget bindings. In binding specification dialog you can trigger auto-completion by pressing CTRL + space bar

  • Once you have created your project, you can re-open this dialog at any time by selecting Project / Properties from the toolbar at the top of the Designer and then clicking Next in the properties wizard.

Leverage aJSON Energia library to construct JSON objects in your firmware

The simplest way to get started publishing JSON objects is to leverage aJSON library that is part of Energia tool. You may download Energia desktop tool from Energia website or use Cloud IDE at dev.ti.com, which has Energia integrated. We recommend that you use examples that are included in aJson library to get a better understanding of how to use aJson library in your own project.

In CCS Cloud IDE, create a new project, choose your device and scroll down to Energia libraries, expand aJson node and choose one the examples.

As an example code below:

bool createJSONString(struct sensorData *localDataPtr)
{

  aJsonObject* root = aJson.createObject();
  aJsonObject* firstChild = aJson.createObject();

  if (root != NULL && firstChild != NULL) {
    aJson.addItemToObject(root, "d",firstChild);
    aJson.addStringToObject(firstChild, "myName",deviceId);
    aJson.addNumberToObject(firstChild, "outside_temperature",localDataPtr->out_temp);
    aJson.addNumberToObject(firstChild, "inside_humidity",localDataPtr->ins_hum);
    aJson.addNumberToObject(firstChild, "humidifier_state",localDataPtr->hum_state);
    aJson.addNumberToObject(firstChild, "inside_temperature",localDataPtr->temp);

    publishJsonString = aJson.print(root);
    aJson.deleteItem(root);
    return true;
  }
  else
    return false;
}

This constructs a JSON object shown below which can then be sent to MQTT broker or through UART over USB connection:

 {
   "d":
  {
     "myName":"f4b85e01868e",
     "outside_temperature":3,
     "inside_humidity":28,
     "humidifier_state":1,
     "inside_temperature":20
  }
}

Gallery examples

The following provides links to the associated target-side code and demonstrates an alternative low-overhead method of parsing of incoming JSON strings sent by the GUI Application. The code also periodically sends the LED status information to the GUI Application:

4.2.3.1. USB-UART : monitor

Using this method for accessing targets variables allows a simple way of creating a GUI Composer Application by specifying global variables in widget bindings.

The main difference is that there is no special HW support required to enable this data exchange mode. This is the only option for MSP430 devices if you would like to use global variables to specify widget bindings.

The main downside is that your program needs to be adjusted to include UART peripheral support and simple monitor that implements a memory read/write protocol. GUI Composer will translate symbol information entered in widget bindings to a memory address and then request the monitor to perform that read and send results back to the host PC. This monitor will require some cycles to be able to provide data to GC app. Overhead is difficult to quantify as it depends on how much data your GC application will pull from the target to update widgets.

In Target Programming page you must select the device that you are working with and upload a program. This is the output of building your CCS Project in CCS Desktop or CCS Cloud. GUI Composer will use symbols contained in that file to obtain memory addresses on the device. In majority of cases the program should already be programmed on your device.

Example: Energia library monitor

You may use an Energia Library that implements target monitor to get started quickly with GUI Composer and an Energia based program. In this case you Energia program includes monitor library and then you can start binding variables to widgets. Please see the Energia-based Monitor tutorial more information.

Example: Barebones monitor

In this example you will need to take source code implementation of target monitor and integrate it with your program. This is best suited if you already have a program and you would like to add monitor based GUI Composer data exchange. You will need to also need to add support for UART peripheral which target monitor will use to complete GUI Composer memory read/write requests.

4.2.3.2. USB-UART : Custom

This method for accessing target data allows full control for how data is sent over UART peripheral.

  • Main advantage of this method is that data to be sent over can be fully controlled as there is no generic protocol overhead. The user defines the protocol. As an example a trivial single float variable in JSON could be represented as {"value":"12345.0"}. Sending this single value requires 19 bytes. If this was sent using binary format (i.e. just the value itself) then entire number could be represented by 4 bytes (on most architectures). This option usually carries minimal overhead for data transmission. However, it is the most complex option for application developer.

The developer needs to:

  • Provide a target application (firmware) that sends/receives the data over UART. This option will require UART peripheral handling code to e added to your target application.

  • Implement host (client) side java script function that parses received data and makes it available to widgets. This function may be provided by following the custom codec steps listed below.

Example: Custom Codec

  1. Create a new project using USB-UART as transport option and add Streaming model with custom from protocol selection. You may optionally provide a program to program the device through Target Programming page. However this is optional if correct firmware is already flashed on the device.

  2. Close the dialog to create a project. Now choose File->New -> Custom Codec File. A javascript file will open that contains boilerplate file and documentation in comments to will help you with parsing custom data and updating widgets.

  3. Please see the Processing Custom UART Data for more information on how to add custom javascript files that allow you to add parsing code.

4.2.3.3. Configuration for XDS communication

This target communication option relies on a debug probes functionality and device (processor) capabilities to provide non-intrusive memory access. It is supported on most Cortex based devices and C2000. For MSP430 devices you would need to use USB-UART : Monitor option to get similar behavior.

In the Target Programming page you must Add a device and program file that will be used for communication. The program file should be generated with symbols. This is the output of building your CCS Project in CCS Desktop or CCS Cloud. At this point program file must be uploaded from your local machine, thus if you have used Cloud IDE to generate your program then you must first download binary file to your local PC and then upload it to GUI Composer. Clicking on the FLASH button allows you to program your device with uploaded binary file.

In Target Communication page you need to add Program Model that will be used to resolve symbols specified in Target Programming page. Program file and device specified in Target Programming will be used. You may then click on Connect button and click on “Console” tab to see whether GUI Composer can successfully connect to your device. You should see a message in console that states Hardware Connected.

Example: Custom Target Configuration (.ccxml) Files

In order to work with custom hardware or do advanced target configurations such as bypassing a device, you can optionally provide your own custom .ccxml file for your GUI Composer Project to use. CCStudio Desktop is the recommended way to create or modify your .ccxml file

To configure your GUI Composer project to use the custom .ccxml file:

  • Rename the file to target_config.ccxml

  • Select Project / Properties from the GUI Composer Designer menu,

  • Click Next to go to the Target Communication Settings page

  • In the Target Program / Symbols section of your project’s Target Communication Settings page, click the UPLOAD button and select the target_config.ccxml file.

  • Using the Executable: droplist, ensure that the executable for your project (if any) is selected

To remove a custom .ccxml file from your GUI Composer project:

  • Select Project / Properties from the GUI Composer Designer menu,

  • Click Next to go to the Target Communication Settings page

  • In the Target Program / Symbols section of your project’s Target Communication Settings page, use the Executable: droplist to select the target_config.ccxml file and click the trash can icon to the right of the droplist.

  • Using the Executable: droplist, ensure that the executable for your project (if any) is selected