Facebook Pixel

AN-00190 ViSi-Genie Generated Header Files

Description This application note shows how to configure Workshop to generate a header file containing a list of defined constants for the objects used in a ViSi-Genie project. For each object, the constant name can be the object name or the alias. The constant value is a two-byte hexadecimal value, the high byte and low byte of which are the object ID and the object index, respectively.
Supported Processor PICASO, DIABLO16
Supported Environment ViSi-Genie
Difficulty Medium

File Downloads
Files

  Description

This application note shows how to configure Workshop to generate a header file containing a list of defined constants for the objects used in a ViSi-Genie project. For each object, the constant name can be the object name or the alias. The constant value is a two-byte hexadecimal value, the high byte and low byte of which are the object ID and the object index, respectively. Below is a screenshot image of the project used in this application note.

Before getting started, the following are required:

and other superseded modules which support the ViSi Genie environment

Visit www.4dsystems.com.au/products to see the latest display module products that use the Diablo16 processor. The display module used in this application note is the uLCD-32PTU, which is a Picaso display. This application note is applicable to Diablo16 display modules as well.

for non-gen4 displays(uLCD-xxx)

for gen4 displays (gen4-uLCD-xxx)

When downloading an application note, a list of recommended application notes is shown. It is assumed that the user has read or has a working knowledge of the topics presented in these recommended application notes.

  Application Overview

When creating a ViSi-Genie project, objects have a standard name and an alias name. The standard name and the alias name are identical by default. The user can modify only the alias name of an object.

When writing the source code for the host program, it would be helpful for the user to be able to import the standard names or alias names of all objects, especially if the ViSi-Genie project is large, i.e. it contains several forms and objects. The user can then make use of the object names or aliases when writing the source code for the host program. This application note shows how this is done.

The ViSi-Genie project attached to this application note consists of two forms. The first form has four winbutton objects, four user LED objects, and a user button object. The second form has three 4D button objects, three user LED objects, and a user button object. Several of these objects are given a unique alias. It is then shown how Workshop is configured to generate a header file containing defined constants for all of the objects.

The GTX tool is then used to analyse the syntax of the messages coming from and sent to the display module. The message for an object is then related to the constant defined for it in the header file. The use of the defined constant (and the header file) is then illustrated using pseudo codes.

  Setup Procedure

For instructions on how to launch Workshop 4, how to open a ViSi-Genie project, and how to change the target display, kindly refer to the section “Setup Procedure” of the application note:

ViSi Genie Getting Started – First Project for Picaso Displays (for Picaso)

or

ViSi Genie Getting Started – First Project for Diablo16 Displays (for Diablo16).

  Create a New Project

Create a New Project

For instructions on how to create a new ViSi-Genie project, please refer to the section “Create a New Project” of the application note

ViSi Genie Getting Started – First Project for Picaso Displays (for Picaso)

or

ViSi Genie Getting Started – First Project for Diablo16 Displays (for Diablo16)

 

  Design the Project

Add Four Winbutton Objects to Form0

Four winbutton objects are added to Form0. These are Winbutton0, Winbutton1, Winbutton2, and Winbutton3. The alias name for a button is appended to the object name.

 

Configure the OnChanged Event of the Winbutton Objects

Each winbutton object is configured to send a message to the serial port when touched.

 

To know more about winbutton objects, their properties, and how they are added to a project, refer to the application note

ViSi-Genie Advanced Buttons

 

Add Four User LED Objects to Form0

Four user LED objects are added to Form0. These are Userled0, Userled1, Userled2, and Userled3. The alias name for a user LED object is appended to the object name.

 

 

To know more about user LED objects, their properties, and how they are added to a project, refer to the application note

ViSi-Genie Digital Displays

 

Add a User Button Object to Form0

A user button object is added to Form0. This is Userbutton0.

 

Configure the OnChanged Event of Userbutton0

Use Userbutton0 for navigating to Form1.

 

To know more about user button objects, their properties, and how they are added to a project, refer to the application note

 ViSi-Genie User Button

 

Configure the OnActivate Event of Form0

Make Form0 send a message to the serial port when it is activated.

 

Add a New Form to the Project

This is Form1.

 

Add Three 4D Button Objects to Form1

Three 4D button objects are added to Form0. These are 4Dbutton0, 4Dbutton1, and 4Dbutton2. The alias name for a 4D button object is appended to the object name.

 

Configure the OnChanged Event of the 4D Button Objects

Each 4D button object is configured to send a message to the serial port when touched.

 

To know more about the 4D button objects, their properties, and how they are added to a project, refer to the application note

 ViSi-Genie 4D Buttons

 

Add Three User LED Objects to Form1

Three user LED objects are added to Form1. These are Userled4, Userled5, and Userled6. The alias name for a user LED object is appended to the object name.

 

Add a User Button Object to Form1

A user button object is added to Form0. This is Userbutton1.

 

Configure the OnChanged Event of Userbutton1

Use Userbutton1 for navigating to Form0.

 

To know more about user button objects, their properties, and how they are added to a project, refer to the application note

 ViSi-Genie User Button

 

Configure the OnActivate Event of Form1

Make Form1 send a message to the serial port when it is activated.

 

Model

Below is a model for an application wherein the host interacts with the display module through the use of WRITE_OBJ and REPORT_EVENT messages.

 

The WRITE_OBJ and REPORT_EVENT messages or commands are two complementary messages that are defined in the ViSi-Genie communications protocol.

WRITE_MAGIC_BYTES

The standard format of WRITE_OBJ message, as defined in section 2.1.2 (Command and Parameters Table) of the ViSi-Genie Reference Manual is:

 

The section “2.1.3.2 Write Object Value Message” further says:

 

REPORT_EVENT

The standard format of a REPORT_EVENT message, as defined in section 2.1.2 (Command and Parameters Table) of the ViSi-Genie Reference Manual is:

 

The section “2.1.3.7 Report Event Message” further says:

 

Configure Workshop to Generate a Header File

Click on the button “Set C Defaults”.

 

Click on the tick box indicated below.

 

  Build and Upload the Project

For instructions on how to build and upload a ViSi-Genie project to the target display, please refer to the section “Build and Upload the Project” of the application note

ViSi Genie Getting Started – First Project for Picaso Displays (for Picaso)

or

ViSi Genie Getting Started – First Project for Diablo16 Displays (for Diablo16).

The uLCD-32PTU and/or the uLCD-35DT display modules are commonly used as examples, but the procedure is the same for other displays.

 

  Check the Generated Header File

Header File Filename Format

Go to the folder where the project files are located. For example, the files for this project are located in the folder shown below. The generated header file is

 

where “Const.h” is the default suffix set in Workshop.

 

Open the Header File

 

Note that the syntax follows that which was set in the “Template” field. We analyse the second item in the list.

 

Note how the elements enclosed by a pair of percentage symbols are replaced with the actual values.

Replace the Object Name with the Alias

Now go back to Workshop and change the value of the template field to that shown below.

 

Note that the available elements are listed below the Generated Files window. Click OK to make the new setting/s effective.

 

Compile and build the project again. The generated file should now be updated accordingly.

 

The Genie Index Element

The Genie index element in the template field will be replaced with a 16-bit hexadecimal value. The high byte of this value is the Genie object ID. The low byte is the Genie object index. To illustrate using the second item in the header file:

 

The object ID for a winbutton object is 0x06. The section “3.3. Object Summary Table” of the ViSi Genie Reference Manual lists all Genie objects and

their IDs. The index “0x00” means that ForwardSwitch is the first winbutton object of the project.

  Identify the Messages

The display module is going to send and receive messages to and from an external host. This section explains to the user how to interpret these messages. An understanding of this section is necessary for users who intend to interface the display to a host. The ViSi Genie Reference Manual is recommended for advanced users.

Use the GTX Tool to Analyse the Messages

Using the GTX or Genie Test eXecutor tool is one option to get the messages sent by the display to the host. Here the PC will be the host. The GTX tool is a part of the Workshop 4 IDE. It allows the user to receive, observe, and send messages from and to the display module. It is an essential debugging tool.

Under the Tools menu click on the GTX tool button.

 

The Genie Test eXecutor window appears.

 

Receive a Message from the Display Module

REPORT_EVENT Message from a Winbutton Object

On the display module, press Winbutton0. The display module will send a REPORT_EVENT message to the PC.

 

The format of this message is:

 

Compare the Genie index element value of Winbutton0 in the header file to the received message.

 

When writing the source code for a program that will run on the host, the user can include the header file and used the defined constants when evaluating REPORT_EVENT messages received from the display module. To illustrate using a pseudo C code:

 

The above function gets called when a message is received from the display module. Assume that the calling function parses the elements of the message received from the serial port and passes them as arguments to eventHandler(…) accordingly.

REPORT_EVENT Message from a Form Object

On the display module, press Userbutton0. The program on the display module will navigate to the second form and will send a REPORT_EVENT message to the PC.

 

The format of this message is:

 

Compare the Genie index element value of Form1 in the header file to the received message.

 

Example of usage through a pseudo C code:

 

REPORT_EVENT Message from a 4D Button Object - On

On Form1 of the display module, press 4Dbutton0. The program on the display module will send a REPORT_EVENT message to the PC.

 

The format of this message is:

 

REPORT_EVENT Message from a 4D Button Object - Off

On Form1 of the display module, press 4Dbutton0 again to turn it off. The program on the display module will send a REPORT_EVENT message to the PC.

 

The format of this message is:

 

Compare the Genie index element value of 4Dbutton0 in the header file to the received message.

 

Example of usage through a pseudo C code:

 

Send a Message to the Display Module

Send a WRITE_OBJ Message to a User LED Object

On the GTX window, click on the green circle for Userled4.

 

Click on the “Set” button below the green circle.

 

The GTX tool sends a WRITE_OBJ message to the display module. Userled4 on the display module should now turn on.

 

The format of this message is:

 

The display module sends back an ACK (acknowledgment) byte to the GTX tool.

 

Compare the Genie index element value of Userled4 in the header file to the received message.

 

When writing the source code for a program that will run on the host, the user can include the header file and used the defined constants when evaluating REPORT_EVENT messages received from the display module. To illustrate using a pseudo C code:

 

Above is a prototype for a function that sends a WRITE_OBJ message to the display. Assume that it works and that the calling function just needs to specify the parameters. To turn on Userled4, we could write:

 

To turn off Userled4, we could write:

Send a WRITE_OBJ Message to a Form Object

On the GTX window, click on the button “Form0” as indicated below.

 

The GTX tool sends a WRITE_OBJ message to the display module. The program on the display module should now navigate to Form0.

 

The format of this message is:

 

The display module sends back an ACK (acknowledgment) byte to the GTX tool.

 

Compare the Genie index element value of Userled4 in the header file to the received message.

 

Below are examples of usage through a pseudo C code.

To navigate to Form0:

 

To navigate to Form1:

Share: