APPLICATION NOTES

ViSi – User Button

DOCUMENT DATE: 1st MAY 2020

DOCUMENT REVISION: 1.2

W W W . 4 D S Y S T E M S . C O M . A U
APPLICATION NOTES 4D-AN-00030

Description Content
This application note provides a first hands-on example with ViSi-Genie and Description...................................................................................................... 2
describes all the steps related to a project. Content ........................................................................................................... 2
Application Overview ..................................................................................... 3
Before getting started, the following are required:
Setup Procedure ............................................................................................. 4

• Workshop4 has been installed according to the document Create a New Project...................................................................................... 4
Workshop4 Installation; Create a New Project .................................................................. 4
• The user is familiar with the Workshop 4 environment and with the Design the Project .......................................................................................... 5
fundamentals of ViSi-Genie, as described in Workshop 4 User Guide Adding a Momentary User Button ............................................... 5
and ViSi-Genie User Guide;
Defining the States of a Momentary User Button 6
• When downloading an application note, a list of recommended
Naming of Objects....................................................................... 9
application notes is shown. It is assumed that the user has read or
Adding a Static Text .................................................................... 9
has a working knowledge of the topics discussed in these
recommended application notes. Adding a New Form .................................................................. 11
Linking Forms ........................................................................... 12
Adding a Toggle User Button .................................................... 12
Defining the States of a Toggle User Button 12
Configuring a User Button as a Toggle Button 13
Adding a User LED ................................................................... 14
Linking Objects 14
Configuring the User LED to Report a Message 15
Create a Button Matrix .............................................................. 16
Adding Three User Buttons 16

Page 2 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

Configuring the Three User Buttons as a Matrix 17 Application Overview

Configuring the Three User Buttons to Report a Message 17
Complete the Form 18 It is often difficult to design a graphical display without being able to see the
immediate results of the application code. ViSi-Genie is the perfect software
The Project 18
tool that allows users to see the instant results of their desired graphical
Build and Upload the Project ....................................................................... 19 layout with this large selection of gauges and meters (called objects or
Identify the Messages .................................................................................. 19 widgets). The user can simply click on the desired widget to select it and
Use the GTX Tool to Analyse the Messages ............................. 19 click on the simulated display to place the widget. Below is the user button
widget, an example of the several widgets available in Workshop.
Launch the GTX Tool 20
The User Button ........................................................................ 20
User Button Icon
Report Event 20
Input and Output Objects 22
Toggle a User Button using the GTX Tool 23 State 0
User Button
Poll the User Button 23
(Momentary)
Proprietary Information ............................................................................... 25 State 1
Disclaimer of Warranties & Limitation of Liability ...................................... 25

State 0

State 1
User Button
(Toggle)
State 2

State 3

Page 3 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

Option 1
Setup Procedure

User Button For instructions on how to launch Workshop 4, how to open a ViSi-Genie
Option 2
Matrix project, and how to change the target display, kindly refer to the section
“Setup Procedure” of the application note:
Option 3
ViSi Genie Getting Started – First Project for Picaso Displays (for Picaso)
A key feature of the user button is that the user can specify the image files or
to be used for each of the states. The simple project developed in this ViSi Genie Getting Started – First Project for Diablo16 Displays (for
application note demonstrates the basic use of a user button. A user button Diablo16).
can be configured to behave as a momentary button, a toggle button, or one
among a group of buttons. Each of these configurations has its own
application. Create a New Project
Create a New Project
The section “Identify the Messages” also discusses the format of the
messages coming from and going to a user button using the GTX Tool in For instructions on how to create a new ViSi-Genie project, please refer to
Workshop. An understanding of this section is essential for users who intend the section “Create a New Project” of the application note
to interface the display to an external host.
ViSi Genie Getting Started – First Project for Picaso Displays (for Picaso)
or
ViSi Genie Getting Started – First Project for Diablo16 Displays (for
Diablo16).

Page 4 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

Design the Project

Everything is now ready to start designing the project. Workshop 4 displays
an empty screen, called Form0. A form is like a page on the screen. The form
can contain widgets or objects like trackbars, sliders, displays or keyboards.
Click on the WYSIWYG (What-You-See-Is-What-You-Get) screen to put the
Below is an empty form. object in place. The WYSIWYG screen simulates the actual appearance of the
display module screen.

Adding a Momentary User Button

To add a user button, go to the Buttons pane then click on the user button
icon.

Page 5 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

The object can be dragged to any desired location and resized to the desired Defining the States of a Momentary User Button
dimensions. The Object Inspector on the right part of the screen displays all A momentary button is enabled when pressed and disabled immediately
the properties of the newly created user button object named Userbutton0. upon release. It can be conveniently used for navigating between forms,
starting and stopping a timer, and navigating between the frames of a video
or a user images object. Here the momentary user button is used to navigate
to the next form. To define the up and up pressed states, click on the ellipsis
dots of the Images property line of the object inspector.

The Image List editor window appears. Click on the Add button to browser
By default, a user button is a momentary button. Note that the property for the image files.
“Momentary” is set to “Yes”.

Take time to experiment with the different properties.

Page 6 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

A standard open window appears and asks for image files. Multiple files can
be selected. The figure below shows the two image files used for
Userbutton0. All the image files used in this demo are saved in the
“.ImgData” folder, which is automatically generated by Workshop when the
project is compiled. After having selected the desired image files, click on
the Open button.

The left-most column lists the image numbers or the states. For additional
information, hover over the Add button:

Note that Userbutton0 is a momentary button. Hence, it only has two states
– ‘up’ and ‘up pressed’.
The Image List editor window is again displayed.

Page 7 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

To illustrate: To rearrange the order, select an image and click on the Up or Down button.
Momentary User Button

State 0
Initial state
or up

Button is State 1 or
pressed up pressed

After having arranged the images to the desired order, click on the OK
button. The WYSIWYG screen is updated with the initial state displayed.

Button is Back to State 0

released or up

Page 8 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

Naming of Objects
Naming is important to differentiate between objects of the same kind. For
instance, suppose the user adds another user button object to the WYSIWYG
screen. This object will be given the name Userbutton1– it being the second
user button object in the program. The third user button will be given the
name Userbutton2, and so on. An object’s name therefore identifies its kind
and its unique index number. It has an ID (or type) and an index.

Userbutton0

Object ID
Object index

Adding a Static Text

To add a static text, go to the Labels pane and click on the static text icon.

Page 9 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

Click on the WYSIWYG screen to place the object. Drag it to any desired Change the caption in the object inspector.
location.

The WYSIWYG screen is updated accordingly.

Page 10 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

Adding a New Form

A new form is added the purpose of which is to demonstrate the use of a
user button configured for toggling. To add a new form, go to the
System/Media pane and select the form icon.

C
A new blank form, named Form1, is generated.

Experimentation with the other properties of the static text is left to the user
as an exercise. To navigate back to Form0 in Workshop, click on the drop-down menu arrow
of the object inspector as shown below and select Form0.

Page 11 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

Do this to navigate between forms.

Linking Forms
Now that there are two forms, a button in Form0 can be used to display The object inspector is updated accordingly.
Form1 (and vice-versa) when the application runs. Here Userbutton0 of
Form0 is configured as a navigation button. In Form0, select Userbutton0,
go to the object inspector, and select the Events tab. Click on the ellipsis
dots of the OnChanged event.

Adding a Toggle User Button

Defining the States of a Toggle User Button

Another user button (Userbutton1) is created in Form1. This button will be
The On event selection window appears. Choose “Form1Activate” and click configured as a toggle button. A toggle button is enabled when pressed, and
OK. stays enabled when released. Another press-and-release is needed to
disable it. For Userbutton1 the following images are used.

Page 12 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

Add the files using the Image Editor window.

State 0
Initial state
or up

State 1 or
Button is pressed
up pressed

Configuring a User Button as a Toggle Button

To configure Userbutton1 to behave as a toggle button, go to the object
inspector and set the momentary property to “No”.

State 2
Button is released
or down

State 3
Button is pressed
or down pressed

Page 13 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

Adding a User LED The object can be dragged and resized. The properties can be edited in the
To add a user LED, go to the Digits pane and select the user LED icon. Object Inspector. Userled0 in Form1 has the following properties:

Click on the WYSIWYG screen to place it.

Linking Objects
Now that Userbutton1 is a toggle button, it can be used to control Userled0.
Go to Userbutton1’s object inspector and click on the ellipsis dots of the
onChanged event.

Page 14 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

The On event selection window appears. Select Userled0Set and click OK. Add another static text object to the form. When done, the form should look
like as shown below.

When the program runs, Userbutton1 will toggle Userled0.

Configuring the User LED to Report a Message

Userled0 can be configured to report a message to an external host
controller when its status has changed. Go to its object inspector and
configure the onChanged event as shown below.

Page 15 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

Create a Button Matrix Adding Three User Buttons

Add another form to the project – Form2. Add three user buttons to Form2. These are Userbutton3, Userbutton4, and
Userbutton5.

This form will contain three user buttons which form a matrix. Buttons in a
matrix behave such that only one button can be enabled at a time. Enabling
another button disables all the other buttons. A matrix of buttons can be
conveniently used as a GUI menu.

First, create a navigation button to link Form1 to Form2. In Form1, a

momentary user button identical to Userbutton0 in Form0 is created.

C
These buttons are identical to Userbutton1 in Form1. Each of these buttons
is configured as a toggle button.

Page 16 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

Configuring the Three User Buttons as a Matrix

To group these buttons into a matrix, edit the Matrix property in the object
inspector.

It is important that all buttons grouped share the same number of matrix,
otherwise pressing on one button will not release the other buttons of the
group.

Configuring the Three User Buttons to Report a Message

A user button can be configured to report a message to an external host
controller when its status has changed. Go to the object inspector of
Userbutton3 and configure the onChanged event as shown below.

Do the same for Userbutton4 and Userbutton5.

Page 17 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

Complete the Form

Add the static objects and a navigation button (Userbutton6) to Form2.

The Project
The project now has three forms. In Form0 is Userbutton0 which is a
momentary button used for displaying the next form – Form1.

Userbutton6 is linked to the first form – Form0.

In Form1 are Userbutton1 and Userbutton2. Userbutton1 is a toggle button

used to control a user LED. Userbutton2 is a momentary navigation button
used to display the next form – Form2.

Page 18 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

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

In Form2 are Userbutton3, Userbutton4, Userbutton5, and Userbutton6. used as examples, but the procedure is the same for other displays.
Userbutton3 to 5 are toggle buttons that form a matrix while Userbutton6
is a momentary button for navigating back to the first form.
Identify the Messages
The display module is going to receive and send messages from and to 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 the first option to get the
messages sent by the screen 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.

Page 19 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

Launch the GTX Tool The User Button

Under Tools menu click on the GTX tool button.
Report Event
When the program starts, navigate to Form1 (the second form) by pressing
the “Next” button on Form0 (the first form) of the display module screen.

A new window appears, with the forms, user buttons, and the user LED
C
created previously.

When Form1 is displayed, toggle the user LED by playing with Userbutton1.

Page 20 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

By following the cycle illustrated below, the user will observe that a message Observe the white area on the right part of the GTX tool window. It displays
is sent to the host upon the release of a press. the message received from the display module.

State 0
Initial state
or up The actual message bytes are those inside the brackets. These values are in
hexadecimal. The figure preceding the actual message is the computer time
at which the message is sent. A label is also included to tell the observer
what the message represents.

time message
State 1 or
Button is pressed
up pressed

The message received is formatted according to the following pattern:

Object Object Value Value
State 2 Command Checksum
Button is released A message is sent to the host Type Index MSB LSB
or down
at this point.
07 21 01 00 01 26

User
REPORT_EVENT Second 0x0001
button

State 3
Button is pressed The message is from Userbutton0, and it contains the hexadecimal value
or down pressed
“0x00001”. When a toggle button is enabled, the value is 0x00001 or simply
1 in decimal. When a toggle button is disabled, the value is 0x0000 or simply
0 in decimal. Verify this by toggling the button back to its very first state.

Page 21 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

result is appended to the end to yield the checksum byte. If the message is
correct, XOR’ing all the bytes (including the checksum byte) will give a result
State 2 of zero. Checking the integrity of a message using the checksum byte shall
Initial state
or down be handled by the host.

Input and Output Objects

Remember that when designing Form1 earlier, Userled0 was configured to
report a message when its status has changed. Userbutton1 on the other
State 3 hand was configured to toggle Userled0 only. The user therefore might have
Button is pressed
or down pressed
expected the message to be similar to:

UserLED Change 17:23:26.552 [07 13 00 00 01 32]

The object ID of a user LED is 0x13. See section 3.3 of the ViSi Genie
State 0 A message is sent to the host Reference Manual for a full list of object IDs. The above is not the case
First state at this point.
or up however since a user LED is classified as an output object. Only input objects
such as a user button can initiate an event. The message therefore is actually
from Userbutton1, although it is Userled0 that was configured to report a
message. To learn more about the input-output classification of Genie
The message sent when the user button has just been disabled is shown objects, refer to section 7 of the ViSi-Genie User Guide.
below.

The checksum is a means for the host to verify if the message received is
correct. This byte is calculated by XOR’ing all bytes in the message from (and
including) the CMD or command byte to the last parameter byte. Then, the

Page 22 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

Toggle a User Button using the GTX Tool The message stands for “Write to the second user button object on the
In the GTX tool window, click on the button indicated below. display module the value 0x0001”.

ACK = 0x06 as shown below

is an acknowledgment from the display module which means that it has

Note that Userbutton1 in Form1 of the display module screen has changed
understood the message.
its state. Also, the white area on the right displays

• in green the messages sent to the display module Poll the User Button
• and in red the messages received from the display module If the user button (or any other output object linked to it) was not configured
to report a message when its status has changed, it is still possible (although
sometimes not advisable) to know its current status (enabled or disabled).
C
To do be able to do this, click on the Query button.
The message sent is formatted according to the following pattern:

Object Object Value Value C

Command Checksum
Type Index MSB LSB

01 21 01 00 01 20
Messages are sent to and received from the display module.
User
WRITE_OBJ Second 0x0001
button

Page 23 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

The messages are formatted according to the following pattern:

Object Object Value Value

Command Checksum
Type Index MSB LSB

00 21 01 - - 20

User
READ_OBJ Second N/A
button

05 21 01 00 01 24

User
REPORT_OBJ Second 0x0001
button

The host sends a READ_OBJ command specifically asking for the value (or
status) of the second user button object. The display module then responds
with the current value of that user button. Communication between a 4D
display module programmed with a ViSi-Genie application and an external
host controller must follow the ViSi-Genie Communications Protocol, which
is defined in the ViSi Genie Reference Manual.

Page 24 of 25 www.4dsystems.com.au
APPLICATION NOTES 4D-AN-00030

Proprietary Information
The information contained in this document is the property of 4D Systems Pty. Ltd. and may be the subject of patents pending or granted, and must not be
copied or disclosed without prior written permission.
4D Systems endeavours to ensure that the information in this document is correct and fairly stated but does not accept liability for any error or omission. The
development of 4D Systems products and services is continuous and published information may not be up to date. It is important to check the current position
with 4D Systems.
All trademarks belong to their respective owners and are recognised and acknowledged.

Disclaimer of Warranties & Limitation of Liability

4D Systems makes no warranty, either expresses or implied with respect to any product, and specifically disclaims all other warranties, including, without
limitation, warranties for merchantability, non-infringement and fitness for any particular purpose.
Information contained in this publication regarding device applications and the like is provided only for your convenience and may be superseded by updates.
It is your responsibility to ensure that your application meets with your specifications.
In no event shall 4D Systems be liable to the buyer or to any third party for any indirect, incidental, special, consequential, punitive or exemplary damages
(including without limitation lost profits, lost savings, or loss of business opportunity) arising out of or relating to any product or service provided or to be
provided by 4D Systems, or the use or inability to use the same, even if 4D Systems has been advised of the possibility of such damages.
4D Systems products are not fault tolerant nor designed, manufactured or intended for use or resale as on line control equipment in hazardous environments
requiring fail – safe performance, such as in the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, direct life
support machines or weapons systems in which the failure of the product could lead directly to death, personal injury or severe physical or environmental
damage (‘High Risk Activities’). 4D Systems and its suppliers specifically disclaim any expressed or implied warranty of fitness for High Risk Activities.
Use of 4D Systems’ products and devices in 'High Risk Activities' and in any other application is entirely at the buyer’s risk, and the buyer agrees to defend,
indemnify and hold harmless 4D Systems from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or
otherwise, under any 4D Systems intellectual property rights.

Page 25 of 25 www.4dsystems.com.au