ViSi-Genie: Getting Started with DIABLO-16 Displays
Description
This application note is intended to demonstrate to the user the interconnection of the 4D Systems DIABLO-16ule with a ZIGBEE personal area network module.
Before getting started, the following are required:
- Any 4D DIABLO-16 touch display module
- A suitable programmer module for:
- non-gen4 displays (uLCD-xxx) 4D Programming Cable or uUSB-PA5-II
- gen4 displays (gen4-uLCD-xxx): 4D-UPA, gen4-PA or gen4-IB paired with 4D Programming Cable / uUSB-PA5
- microSD (uSD) card
- Workshop4 has been installed according to the the user guide
The display module used in this application note is the uLCD-32DT, which is a discontinued product. The procedures described in this application note however are also applicable to other DIABLO-16play modules. Users should have no problem locating the programming header visually or by consulting the datasheet.
Downloadable Resources
Here's a the sample project file for this application note.
ViSi-Genie: DIABLO-16 First Project
Application Overview
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 tool that allows users to see the instant results of their desired graphical layout with this large selection of gauges and meters (called objects or widgets). The user can simply click on the desired widget to select it and click on the simulated display to place the widget. The following are the widgets used in this application note.
The simple project developed in this application note demonstrates basic touch functionality and object interaction. The user moves or touches the trackbar, and the meter and LED digits change their values to correspond with the trackbar’s change in status. By default, input objects such as the trackbar respond to touch. The user can configure an input object to drive an output object such as the meter or the LED digits. The project also illustrates how input objects are configured to send messages to an external host controller and how these messages are interpreted.
Setup Procedure
After Workshop4 installation, a shortcut is optionally generated in the Desktop
Launch Workshop4 by double-clicking on the icon.
Alternatively, open the application by searching it from Windows Start menu.
Load the Example
This document comes with a ViSi-Genie program you can download from Downloadable Resources section.
For users who want to learn how to create a ViSi-Genie application, proceed to the next section.
Workshop4 opens and displays a blank Recent page
To load the existing project, click on Open.
A standard open window asks for a ViSi-Genie project.
Now, check the type of the screen module by selecting the Project menu.
If using a different display module, change the target display module by clicking on the display button.
The Change Display window appears.
Select the appropriate screen on the drop-down list and define the orientation.
…and confirm by clicking on 
.
Creating a New Project
Opening Workshop4 displays the Recent page.
To create a new project, there are two options. Click on the top left-most icon, New.
Or Click on the icon beside Create a new Project.
The Choose-Your-Product window appears.
You may filter the products by clicking on the filter dropdown button
For most uLCD DIABLO-16 products, select DIABLO-16
Since uLCD-32DT is a legacy product, it can be found under Legacy DIABLO-16 instead
Select the appropriate screen and preferred orientation. The screen used in this example is a uLCD-32DT (Landscape Rotated/Reversed).
Select ViSi-Genie from the project environment selection.
Design the Project
Everything is now ready to start designing the project. Workshop4 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. Below is an empty form.
At the end of this section, the user will be able to create a form with three objects. The final form will look like as shown below, with the labels excluded.
The procedure for adding each of these objects will now be discussed.
Adding A Meter
The meter changes its value while the trackbar is being moved. To add a meter, go to the Gauges pane then click on the meter icon.
Click on the WYSIWYG (What-You-See-Is-What-You-Get) screen to put the meter in place. The WYSIWYG screen simulates the actual appearance of the display module screen.
The object can be dragged to any desired location and resized to the desired dimensions. The Object Inspector on the right part of the screen displays all the properties of the newly created meter object named Meter0.
Feel free to experiment with the different properties. Take note of the maximum and minimum values. These correspond to the maximum and minimum values of the meter widget.
When finished, the WYSIWYG screen will look similar to that shown below.
Naming of Objects
Naming is important to differentiate between objects of the same kind. For instance, suppose the user adds another meter to the WYSIWYG screen. This object will be given the name Meter1 – it being the second meter in the program. The third meter will be given the name Meter2, 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.
Adding LED Digits
The LED digits object updates its value when the value of Meter0 has changed. To add a LED digits object, go to the Digits pane and select the first icon.
Click on the WYSIWYG screen to place the object and go to the Object inspector and set the following property values.
The appearance of the LED digits object is shown below.
Adding a Trackbar
The trackbar responds to the user’s touch and drives the meter and LED digits. To add a trackbar, go to the Inputs pane and click on the trackbar icon.
Click on the WYSIWYG screen to place the trackbar. Drag the object to any desired location.
In the Object Inspector, the minimum value is 0 and maximum value is 100 by default.
Configuring the Trackbar
The OnChanged Event
An input object such as the trackbar can be configured to report a message to an external host every time its (trackbar’s) status has changed. To do this, click on the Events tab in the object inspector and click on the 
symbol in the OnChanged line.
The On event selection window appears. Select Report Message and click OK.
The OnChanged event property is now updated.
With this, every time the trackbar has moved or its status has changed, it sends a message to the external host.
Tip
The use of the Report Message option in the On event selection window is one way by which the display module can communicate with an external host controller. For users who intend to interface the display to an external controller (such as the Arduino), this option allows an input object of the display module to update the host of its status.
The message or data sent has a format which the host must understand. Please refer to the ViSi-Genie Reference Manual for information about the Genie Command Protocol.
The OnChanging Event
An input object such as the trackbar can also be configured to change the status of another object while its status is changing. To do this, click on the Events tab in the object inspector and click on the symbol in the OnChanging line.
The On event selection window appears. Select Meter0Set and click OK.
The OnChanging event property is now updated.
Now while the trackbar is being moved, it constantly sends its values to Meter0. Meter0 receives and displays these values on the fly.
Tip
For the OnChanged event, the trackbar will send a value when the stylus or finger moving it is lifted off the screen. Selecting the OnChanging event, on the other hand, causes the trackbar to send values while it is being moved (the moving finger or stylus is not lifted off yet).
To learn more about OnChanged and OnChanging events, read the application note ViSi-Genie: onChanging and onChanged Events
Linking Objects
After having linked Trackbar0 to Meter0, it is also possible to further extend the link by configuring Meter0 to send its value to Leddigits0. To do this, click on Meter0 to select it. Select the Events tab in the object inspector and click on the symbol in the OnChanged line.
The On event selection window appears. Select Leddigits0Set and click OK.
The Events pane is now updated.
Now while Trackbar0 is being moved, it constantly sends its values to Meter0. Meter0 receives and displays these values while simultaneously updating Leddigits0. To learn more about how objects are linked and classified (input/output/combined), refer to the ViSi-Genie User Guide.
Build and Upload the Project
Save the Program
Save the program with the desired file name first.
Connecting a gen4 Display Module
For gen4 display modules, connect it to the PC using a 4D-UPA, gen4-PA or a gen4-IB paired with either a 4D Programming Cable or a uUSB-PA5-II.
Note
Depending on your system you might be required to install the device drivers manually. Please refer to the respective datasheets for information on where to find the appropriate driver.
Using the 4D-UPA
Similar to how a gen4 Display connects with the 30-way FFC, 4D-UPA also connects with the silver (connector) side up
After connecting both the FFC from the gen4 display and a microUSB cable connected to the computer, here's a completed setup
Note
gen4-IB and gen4-PA also connects with the silver (connector) side of the FFC facing upwards
Using the 4D Programming Cable
Confirm the pins as shown
and connect the Programming Cable to the gen4-IB
Here's a complete setup
Using the uUSB-PA5 Programming Adaptor
Confirm the pins as shown
and connect the uUSB-PA5(-II) to the gen4-IB
Here's a complete setup
Connecting non-gen4 Display Modules
For non-gen4 display modules, connect it to the PC using a uUSB-PA5-II or a 4D Programming Cable.
Using the uUSB-PA5 Programming Adaptor
Connect a 5-way cable to the uLCD ensuring the connection is as shown.
Connect the other end of the 5-way cable to the uUSB-PA5. The uUSB-PA5 should also be connected to the computer using a miniUSB cable that supports data transfer.
Here's a complete setup
Using the 4D Programming Cable
Connect the programming cable to the uLCD ensuring the connection is as shown.
Here's a complete setup
Check if the Display Module is Detected
Go to the Comms menu to check if the module is detected.
The violet light indicates no programming module is currently connected.
With the display module connected to the 4D USB programming cable (or uUSB-PA5), plug the cable into the USB port. Click on the drop-down list and select the COM port allocated to the cable.
Workshop4 will start scanning the port for any 4D display module connected.
The light turns red when no module is attached to the selected port:
The light goes blue when the connection is established.
Tip
Click the indicator LED/Button to rescan the selected port
Note
The color of the circular button/led indicates different statuses:
| Color | Preview | Description |
|---|---|---|
| Violet |  |
No programming module is currently connected |
| Yellow |  |
Port is being scanned for a 4D display module |
| Red |  |
No device detected or device isn't responding |
| Blue |  |
Device is detected |
If the connected target display cannot be detected, double check all connections, ensure that the drivers are correctly installed, and verify the correct COM port allocation for the programming module.
Check continuity of the 5-way cable and try replacing the USB-to-miniUSB cable (if using a uUSB-PA5) as well. Some USB-to-miniUSB cables transfer power only and not data. To learn how to update the firmware or PmmC and driver of the display, read General: How to Update the PmmC for DIABLO-16.
Insert the uSD Card to PC
For DIABLO-16 display modules, a uSD card shall be FAT16-formatted, and partition can't exceed 4GB. Connect the uSD card to your computer using an external uSB module or a built-in card reader.
Check if the uSD card is properly mounted and connected. Here it is mounted as drive E:
Program Destination
Choose the destination of the project. Select the Project menu and click on Flash as the destination.
Compile and Download
After making sure that the device is detected, go to the Home menu and click on the Build Copy/Load button.
The left button forces a build of the graphics files all the time. Clicking on the left icon always builds and copies the graphics files to the uSD card and downloads the program to the display module. Use the left icon to be sure that the graphics files and program are always up-to-date, i.e., they include the latest changes made.
The right button builds the graphics files only when Workshop detects any change made on the WYSIWYG screen and/or the Object Inspector.
When no changes are detected, clicking on the right button will simply cause Workshop to copy the graphics files to the uSD card and load the program to the display. The right button is useful for loading a single Genie application to multiple displays and uSD cards. The left button is the better choice when the user wants to make sure that the graphics files are updated all the time.
Note
For larger ViSi-Genie programs, Worskhop may take some time to build the graphics files.
After clicking the left build button, Workshop builds and downloads the program to the display module.
Workshop will prompt the user for the uSD card. Select the drive on the drop down list then click on OK.
A progress bar is displayed while the necessary files are being copied to the uSD card. Workshop copies two files to the uSD card –the GCI and the DAT files. The GCI file contains the graphics and the DAT file contains a list of the objects inside the GCI file. These files will be accessed by the program when the display module is turned on.
Afterwards, Workshop downloads the program to the flash memory of the display module.
Finally, the message box displays the code size and confirms that the download to the flash memory has been successful.
Insert the uSD Card to the Display Module
Properly disconnect the uSD card from the PC and plug it to the uSD Card slot of the display module.
Power on the display to start the project and run it on the screen.
Play with the project and observe how the objects interact.
Identify the Messages
The display module is going to generate and send messages 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 Message
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 Workshop4 IDE. It allows the user to receive, observe, and send messages from and to the display module. It is an essential debugging tool.
Launch the GTX Tool
Under Tools menu click on the GTX tool button.
A new window appears, with the form and objects created previously.
The Trackbar
Change the Status of the Trackbar
In the GTX tool window, use the mouse to move the slider of the trackbar and press Set. On the display module, note that the slider of the trackbar has moved.
Also, messages are sent to and received from the display module.
The white area on the right of the GTX window displays
- in green the messages sent to the display module
- and in red the messages received from the display module
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.
The message sent is formatted according to the following pattern:
| Command | Object Type | Object Index | Value MSB | Value LSB | Checksum |
|---|---|---|---|---|---|
| 01 (WRITE_OBJ) | 05 (Trackbar) | 00 | 00 | 28 | 2C |
The message stands for Write to the first trackbar object on the display module the value 0x0028. The value of the trackbar is specified by Value MSB and Value LSB which gives 0x0028. Converting this to decimal will yield the value 40.
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 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 of zero. Checking the integrity of a message using the checksum byte shall be handled by the host.
ACK = 0x06 as shown below
is an acknowledgment from the display module which means that it has understood the message.
Message from the Trackbar
Remember that Trackbar0 was configured to Report a Message when its status has changed. Now move the trackbar on the display module with a stylus or a finger. Observe the message sent by the display module to the PC.
The message from a trackbar is formatted according to the following pattern:
| Command | Object Type | Object Index | Value MSB | Value LSB | Checksum |
|---|---|---|---|---|---|
| 07 (REPORT_EVENT) | 05 (Trackbar) | 00 | 00 | 50 | 52 |
where, the LSB and MSB value is combine as 0x0050.
Query the Value of the Trackbar
Suppose the trackbar object is not configured to report an event when it has moved. The PC can ask the display module for the value of the trackbar by sending a message.
Now on the display module randomly move the trackbar and press Query in the GTX window.
Observe the message area.
The PC sends a request message. The display module replies with the current value of the trackbar.
The messages sent is formatted according to the following patterns below with LSB and MSB values are not applicable.
| Command | Object Type | Object Index | Value MSB | Value LSB | Checksum |
|---|---|---|---|---|---|
| 00 (READ_OBJ) | 05 (Trackbar) | 00 | - | - | 05 |
And the received message is formated with the following patterns.
| Command | Object Type | Object Index | Value MSB | Value LSB | Checksum |
|---|---|---|---|---|---|
| 05 (REPORT_OBJ) | 05 (Trackbar) | 00 | 00 | 1D | 1D |
REPORT_EVENT vs. REPORT_OBJ
It is important to take note of the difference between REPORT_EVENT and REPORT_OBJ. REPORT_EVENT occurs if the user selects the event of a widget or object in Workshop to be "Report Message". There is no need for the host to ask the display module for the status or value of the object. The object independently sends its current status since it was configured to do so. Whereas REPORT_OBJ is a result of the user doing a read of an object from the host, using the query button.
Experimentation with the different objects using the GTX tool is now left to the user as an exercise. The following tables are shown below as a reference. Consult the ViSi-Genie Reference Manual for more information regarding: